Skip to navigation
REST RPC APICustomers

Create

View as Markdown

Creates a customer and returns it with 201.

This endpoint accepts the Application API Scope only. Storefront API Scope signatures are rejected. merchant must be your merchant public ID, or the request returns 403.

Only merchant is always required. Your merchant account’s required-field settings can also require merchant_user_id, first_name, last_name, email, or other fields, and a missing one returns 400.

If a customer with this merchant_user_id already exists, nothing is created or changed. A request with the same merchant_user_id, email, and user_token_id as that customer returns 400; any other request returns 201 with the existing customer as it was.

Authentication

x-api-keystring

Application API Scope — server-to-server, sent in the x-api-key header. See Authentication.

Request

This endpoint expects an object.
merchantstringRequired

Your merchant public ID. It must match the merchant you authenticate as, or the request returns 403.

merchant_user_idstringOptional
Your customer's ID in your ecommerce platform. The other customer endpoints look customers up by this ID.
session_idstringOptional

Session ID, from the og_session_id cookie. Ordergroove generates one if you leave it out.

user_token_idstringOptional
User Token ID
first_namestringOptional
Customer first name
last_namestringOptional
Customer last name
emailstringOptional
Customer email
phone_numberstringOptional
Customer phone number
phone_typeintegerOptional

Customer phone type: 0 (invalid), 1 (landline), 2 (mobile), or 3 (VoIP)

livebooleanOptional

Whether the customer account is active. Defaults to true.

extra_datastringOptional

Extra information to store on the customer, as a JSON-encoded string of key/value pairs, up to 1,024 characters.

localestring or integer or nullOptional

The customer’s locale, as a locale code such as en-us or a numeric locale ID. Codes are case-insensitive, and hyphens and underscores are interchangeable. Responses always return the numeric ID.

experiencesmap from strings to booleansOptional

Experiences to check the customer against, keyed by experience name, for example {"reorder": true}. For each key, Ordergroove checks that the request includes every field your merchant account’s settings require for that experience, and returns 400 if any is missing. The values are ignored, and experiences aren’t saved on the customer.

price_codestringOptional
Customer price code

Response

201
merchantstringOptional
Your merchant public ID.
merchant_user_idstringOptional
Your customer's ID in your ecommerce platform.
session_idstringOptional
Session ID, from the request or generated by Ordergroove.
user_token_idstringOptional
User Token ID. Empty if none was sent.
first_namestringOptional
Customer first name
last_namestringOptional
Customer last name
emailstringOptional
Customer email
phone_numberstring or nullOptional
Customer phone number
phone_typeinteger or nullOptional

Customer phone type: 0 (invalid), 1 (landline), 2 (mobile), or 3 (VoIP)

livebooleanOptional
Whether the customer account is active.
createdstringOptional
When the customer was created.
last_updatedstringOptional
When the customer was last updated.
last_loginstring or nullOptional

When the customer last logged in. null until they do.

extra_datastring or nullOptional

Extra information stored on the customer, as a JSON-encoded string.

localeinteger or nullOptional

The customer’s locale as a numeric ID, for example 1 for en-us, even if the request sent a locale code.

price_codestring or nullOptional
Customer price code

Errors

400
Bad Request Error
403
Forbidden Error