{ "openapi": "3.1.1", "info": { "title": "Customers API", "description": "This API can be used to retrieve, create, update and delete customers as well as customer information.", "contact": { "name": "Connections Platform Team", "x-slack-channel": "#raven", "x-source-code": "https://github.com/gdcorp-im/raven" }, "version": "1.2.0" }, "servers": [ { "url": "https://api.godaddy.com/v1/commerce", "description": "Production" } ], "tags": [ { "name": "Customer", "description": "Create, read, and update customer profiles within a store." } ], "paths": { "/stores/{storeId}/customers": { "get": { "tags": [ "Customer" ], "description": "This endpoint can be used to retrieve a list of customers for a specific store. Deleted customers are excluded by default.", "summary": "Get customers", "operationId": "CustomersList", "parameters": [ { "$ref": "#/components/parameters/storeId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/pageToken" }, { "name": "totalRequired", "in": "query", "required": false, "description": "Indicates whether the response should include the total number of items and pages through response properties totalItems and totalPages respectively.", "schema": { "type": "boolean" } }, { "name": "queryString", "in": "query", "description": "Search term - this string will be matched as a starts with for all text fields", "required": false, "schema": { "type": "string" } }, { "name": "nonEmptyFields", "in": "query", "description": "Filter customers by presence of at least one of these fields", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "FIRST_NAME", "LAST_NAME", "PHONE" ] } } }, { "name": "emptyFields", "in": "query", "description": "Filter customers by absence of at least one of these fields", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "FIRST_NAME", "LAST_NAME", "PHONE" ] } } }, { "name": "allNonEmptyFields", "in": "query", "description": "Filter customers by presence of all of these fields", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "FIRST_NAME", "LAST_NAME", "PHONE" ] } } }, { "name": "allEmptyFields", "in": "query", "description": "Filter customers by absence of all of these fields", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "FIRST_NAME", "LAST_NAME", "PHONE" ] } } }, { "name": "externalIdentifiers", "in": "query", "description": "Filter customers by external identifier; provide as comma separated values in the form `type:value` (eg: `poynt:123,asin:B0B9F7WNQH`)", "schema": { "type": "array", "items": { "type": "string", "description": "External identifier type and value separated by a colon, eg `poynt:123`" } } }, { "name": "updatedAtStart", "in": "query", "description": "Filter customers whose updatedAt is >= the specified date", "required": false, "schema": { "$ref": "#/x-ext/37bf2ab" } }, { "name": "updatedAtEnd", "in": "query", "description": "Filter customers whose updatedAt is <= the specified date", "required": false, "schema": { "$ref": "#/x-ext/37bf2ab" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort expression accepted by the underlying customer search service", "schema": { "type": "string" } }, { "name": "excludeGuestCustomers", "in": "query", "required": false, "description": "Whether to exclude guest customers (those without an associated user record). Defaults to true.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Request was successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "required": [ "customers" ], "properties": { "customers": { "type": "array", "description": "Array of customers", "items": { "$ref": "#/components/schemas/Customer" } } } } ] } } } }, "401": { "$ref": "#/components/responses/401", "x-error-code": [ "INVALID_AUTH_TOKEN" ] }, "403": { "$ref": "#/components/responses/403", "x-error-code": [ "DEACTIVATED_STORE" ] }, "404": { "$ref": "#/components/responses/404", "x-error-code": [ "NOT_FOUND_STORE_ID" ] }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422", "x-error-code": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ] }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "PAT": [ "commerce.customer:read" ] } ] }, "post": { "tags": [ "Customer" ], "description": "This endpoint can be used to create or de-duplicate - using channel data - and merge into existing customer. If the provided channels differ from existing customer data, a new customer will be created. This endpoint will not remove any existing data and is additive in cases where merges occur.", "summary": "Create a new customer", "operationId": "CommerceCustomersCreate", "parameters": [ { "$ref": "#/components/parameters/storeId" } ], "requestBody": { "description": "Customer data to import", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } } }, "responses": { "202": { "description": "A CUSTOMER_CREATE action was successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionResponse" } } } }, "401": { "$ref": "#/components/responses/401", "x-error-code": [ "INVALID_AUTH_TOKEN" ] }, "403": { "$ref": "#/components/responses/403", "x-error-code": [ "INVALID_AUTH_TOKEN_TYPE", "DEACTIVATED_STORE" ] }, "404": { "$ref": "#/components/responses/404", "x-error-code": [ "NOT_FOUND_STORE_ID" ] }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422", "x-error-code": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ] }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "PAT": [ "commerce.customer:create" ] } ] } }, "/stores/{storeId}/customers/{customerId}": { "patch": { "tags": [ "Customer" ], "description": "This endpoint can be used to update the information of a specific customer using the store and customer ID.", "summary": "Update customer", "operationId": "CommerceCustomersUpdate", "parameters": [ { "$ref": "#/components/parameters/customerId" }, { "$ref": "#/components/parameters/storeId" } ], "requestBody": { "description": "Customer data to import", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" } } } }, "responses": { "202": { "description": "A CUSTOMER_UPDATE action was successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerActionResponse" } } } }, "401": { "$ref": "#/components/responses/401", "x-error-code": [ "INVALID_AUTH_TOKEN" ] }, "403": { "$ref": "#/components/responses/403", "x-error-code": [ "INVALID_AUTH_TOKEN_TYPE", "DEACTIVATED_STORE" ] }, "404": { "$ref": "#/components/responses/404", "x-error-code": [ "NOT_FOUND_STORE_ID", "NOT_FOUND_CUSTOMER" ] }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422", "x-error-code": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ] }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "PAT": [ "commerce.customer:update" ] } ] }, "get": { "tags": [ "Customer" ], "description": "Retrieve the information of a single customer using the store and customer IDs.", "summary": "Get customer by ID", "operationId": "FetchCustomer", "parameters": [ { "$ref": "#/components/parameters/customerId" }, { "$ref": "#/components/parameters/storeId" } ], "responses": { "200": { "description": "Request was successful", "content": { "application/json": { "schema": { "type": "object", "required": [ "customer", "links" ], "properties": { "customer": { "$ref": "#/components/schemas/Customer" }, "links": { "type": "array", "description": "HATEOAS link relations", "items": { "$ref": "#/x-ext/590647a" } } } } } } }, "401": { "$ref": "#/components/responses/401", "x-error-code": [ "INVALID_AUTH_TOKEN" ] }, "403": { "$ref": "#/components/responses/403", "x-error-code": [ "DEACTIVATED_STORE" ] }, "404": { "$ref": "#/components/responses/404", "x-error-code": [ "NOT_FOUND_STORE_ID", "NOT_FOUND_CUSTOMER" ] }, "422": { "$ref": "#/components/responses/422", "x-error-code": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ] }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "security": [ { "PAT": [ "commerce.customer:read" ] } ] } } }, "components": { "schemas": { "Request": { "type": "object", "required": [ "actionId", "status", "customerIds", "undoSupport", "links" ], "properties": { "actionId": { "description": "Identifier for the asynchronous action created by the original mutating call. The same UUID returned in the original `links[rel=request]` href.", "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ActionStatuses" }, "undoSupport": { "description": "How completely this action can be undone. `NONE` means no automated undo is supported for this action type; `PARTIAL` means some side effects can be reversed; `FULL` means the action is fully reversible.", "type": "string", "enum": [ "NONE", "PARTIAL", "FULL" ] }, "errors": { "description": "Per-record failures from the worker that processed this action. `null` (rather than absent) when there were no errors.", "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CustomerError" } }, "customerIds": { "description": "IDs of the customer records created by the request. Always emitted (empty array when no customers were created — for example update, delete, and activity-create requests).", "type": "array", "items": { "type": "string", "format": "uuid" } }, "links": { "description": "HATEOAS link relations. Always includes a `self` link; for create-style actions also includes a `customer` link.", "type": "array", "items": { "$ref": "#/x-ext/590647a" } } } }, "ActionStatuses": { "type": "string", "description": "The possible statuses an action can be in", "enum": [ "FAILED", "PARTIAL_SUCCESS", "PENDING", "SUCCESS" ] }, "Address": { "type": "object", "properties": { "address1": { "type": "string", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$" }, "address2": { "type": "string", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$" }, "city": { "type": "string", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$" }, "state": { "type": "string", "description": "State or province or territory", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$" }, "postalCode": { "type": "string", "description": "Postal or zip code", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$" }, "country": { "type": "string", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,2}$", "description": "Country ISO code" }, "label": { "type": "string", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,'#*@/& ]{,100}$", "description": "A descriptive name for the address" } } }, "Customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerBase" }, { "$ref": "#/components/schemas/UpdatedAt" }, { "$ref": "#/components/schemas/ListKeys" }, { "type": "object", "required": [ "customerId", "createdAt" ], "properties": { "joined": { "description": "Whether the customer has been joined with one or more other customers to create a single customer", "type": "boolean", "default": false }, "orderCount": { "description": "Number of orders the customer has made", "type": "integer", "minimum": 0 }, "profileImageUrl": { "description": "URL of the profile image for the customer. Nullable.", "type": [ "string", "null" ], "format": "url" }, "paymentCount": { "description": "Number of payments the customer has completed", "type": "integer", "minimum": 0 }, "notes": { "description": "Free-form notes attached to the customer. Nullable.", "type": [ "string", "null" ] }, "createdAt": { "description": "ISO 8601 timestamp the customer record was created.", "$ref": "#/x-ext/37bf2ab" }, "source": { "description": "Source application that originally created the customer. Most modern records emit one of the values from the `Source` enum, but legacy records may carry the same value lowercased (e.g. `commerce` instead of `COMMERCE`). Treat the field as case-insensitive when comparing.\n", "type": "string" }, "externalIdentifiers": { "description": "Array of external identifiers associated with this customer. Only emitted when the customer has at least one external identifier. Replaces the legacy singular `externalIdentifier` wrapper.", "type": "array", "items": { "type": "object", "required": [ "externalId", "source" ], "properties": { "externalId": { "type": "string", "description": "The external id for the customer in another service" }, "source": { "type": "string", "description": "The name of the service from which the external id originates", "examples": [ "INVOICE" ] } } } } } } ] }, "CustomerBase": { "allOf": [ { "$ref": "#/components/schemas/CustomerId" }, { "type": "object", "required": [ "firstName", "lastName" ], "properties": { "firstName": { "type": "string", "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,\\(\\)\\@&' ]*$", "maxLength": 50, "examples": [ "Fredrick" ] }, "lastName": { "type": "string", "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,\\(\\)\\@&' ]*$", "maxLength": 50, "examples": [ "Smith" ] }, "organization": { "type": [ "string", "null" ], "format": "organization-name", "maxLength": 100, "pattern": "^[\\u0080-\\uFFFFa-zA-Z0-9\\-.,\\(\\)\\\\@&!' +]*$", "examples": [ "GoDaddy" ] }, "jobTitle": { "type": [ "string", "null" ] }, "addresses": { "description": "Array of customer addresses. Note that currently only one address is supported", "items": { "$ref": "#/components/schemas/Address" }, "type": "array", "maxLength": 10, "default": [] }, "emails": { "description": "Array of email addresses. Contact details must be sent as this array of `Email` objects — a top-level scalar `email` string is accepted with a 202 but silently discarded, so always verify with a GET.\n", "items": { "$ref": "#/components/schemas/Email" }, "type": "array", "maxLength": 10, "default": [] }, "instantMessages": { "description": "Array of instant messaging accounts associated with the customer", "items": { "$ref": "#/components/schemas/InstantMessage" }, "type": "array", "maxLength": 10, "default": [] }, "socialProfiles": { "description": "Array of social profiles associated with the customer", "items": { "$ref": "#/components/schemas/SocialProfile" }, "type": "array", "maxLength": 10, "default": [] }, "phones": { "description": "Array of phone numbers. As with `emails`, phone details must be sent as this array of `Phone` objects — a top-level scalar `phone` string is accepted with a 202 but silently discarded.\n", "items": { "$ref": "#/components/schemas/Phone" }, "default": [], "type": "array", "maxLength": 10 }, "urls": { "description": "Array of urls associated with the customer", "items": { "$ref": "#/components/schemas/Url" }, "type": "array", "maxLength": 10, "default": [] } } } ] }, "CustomerCreate": { "type": "object", "required": [ "customer", "source" ], "properties": { "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerBase" }, { "$ref": "#/components/schemas/CustomerExternalIdentifier" }, { "$ref": "#/components/schemas/ListKeys" } ] }, "source": { "$ref": "#/components/schemas/Source" } } }, "CustomerUpdate": { "description": "Body shape for `PATCH /stores/{storeId}/customers/{customerId}`. Note that `source` is **optional** on update — the API does not require it (and production clients such as `mwc-core` do not send it on update calls).\n", "type": "object", "required": [ "customer" ], "properties": { "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerBase" }, { "$ref": "#/components/schemas/CustomerExternalIdentifier" }, { "$ref": "#/components/schemas/ListKeys" }, { "$ref": "#/components/schemas/UpdatedAt" } ] }, "source": { "$ref": "#/components/schemas/Source" } } }, "CustomerDataPoint": { "type": "object", "required": [ "periodStartedAt", "periodEndedAt", "count" ], "properties": { "periodStartedAt": { "description": "Start of range included in bin", "$ref": "#/x-ext/37bf2ab" }, "periodEndedAt": { "description": "End of range included in bin", "$ref": "#/x-ext/37bf2ab" }, "count": { "description": "Count of new unique customers", "type": "integer", "format": "integer-positive" } } }, "CustomerError": { "description": "Per-record failure entry surfaced inside `Request.errors` for actions that processed multiple customers. Carries the offending `customerId` plus the same fields as the generic `Error` envelope.\n", "allOf": [ { "$ref": "#/components/schemas/CustomerId" }, { "$ref": "#/components/schemas/Error" } ] }, "CustomerId": { "description": "Customer identifier that is unique within current Store", "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" } } }, "CustomerExternalIdentifier": { "type": "object", "properties": { "externalIdentifier": { "type": "object", "properties": { "externalId": { "description": "The external id for the customer in another service", "type": "string", "maxLength": 255 }, "source": { "description": "The name of service from which the external id originates", "type": "string", "maxLength": 255, "examples": [ "INVOICE" ] } }, "required": [ "externalId", "source" ] } } }, "CustomerActionResponse": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string" }, "method": { "type": "string" }, "rel": { "type": "string" } } } } }, "required": [ "links" ] }, "Email": { "required": [ "email" ], "properties": { "email": { "$ref": "#/x-ext/4945a71" }, "label": { "description": "A user provided name for the email address", "type": "string", "maxLength": 255 }, "default": { "description": "Indicates whether the email is the primary email.", "type": "boolean" } }, "type": "object" }, "InstantMessage": { "required": [ "accountKey" ], "properties": { "accountKey": { "description": "An accountKey for the instant messaging account", "type": "string", "maxLength": 255 }, "label": { "description": "A user provided name for the external service", "type": "string", "maxLength": 255 } }, "type": "object" }, "ListKeys": { "required": [ "listKeys" ], "properties": { "listKeys": { "description": "List memberships that should be changed for the customer", "items": { "type": "string", "format": "uuid" }, "type": "array" } }, "type": "object" }, "PaginatedResponse": { "type": "object", "required": [ "links" ], "properties": { "links": { "description": "HATEOAS link relations", "type": "array", "items": { "$ref": "#/x-ext/590647a" } }, "totalItems": { "type": "integer", "description": "The total number of items in the full result set. Only returned if the `totalRequired` param is true" }, "totalPages": { "type": "integer", "description": "The total number of pages of results in the full result set. Only returned if the `totalRequired` param is true" } } }, "Phone": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "description": "A customer phone number", "type": "string", "format": "phone", "maxLength": 17 }, "label": { "description": "A user provided name for the phone number. Nullable.", "type": [ "string", "null" ], "maxLength": 255 }, "default": { "description": "Indicates whether the phone is the primary phone.", "type": "boolean" }, "blocked": { "description": "Indicates whether outbound communication to this phone number is blocked.", "type": "boolean" } } }, "SocialProfile": { "required": [ "accountKey" ], "properties": { "accountKey": { "description": "An accountKey for the social profile", "type": "string", "maxLength": 255 }, "label": { "description": "A user provided name for the external service", "type": "string", "maxLength": 255 } }, "type": "object" }, "Source": { "description": "Source application of the interaction. Use one of the listed uppercase values when sending; legacy records returned by the API may carry the same value lowercased.\n", "type": "string", "enum": [ "COMMERCE", "CONTACTS", "CONVERSATIONS", "EMAIL_MARKETING", "GDSOCIAL", "GOPAY", "INVOICE", "ONLINE_APPOINTMENTS", "ONLINE_STORE", "PAYMENTS", "POYNT", "WEBSITE_BUILDER", "ZAPIER" ] }, "UniqueCustomerData": { "type": "object", "properties": { "totalCount": { "description": "Total count of unique customers across date range", "type": "integer", "format": "integer-positive" }, "total": { "type": "array", "description": "Count of all unique customers", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "inPerson": { "type": "array", "description": "Unique count of customers with in person activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "virtualTerminal": { "type": "array", "description": "Unique count of customers with virtual terminal activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "invoicing": { "type": "array", "description": "Unique count of customers with invoicing activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "onlinePayLinks": { "type": "array", "description": "Unique count of customers with online pay link activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "ecommerce": { "type": "array", "description": "Unique count of customers with ecommerce activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "mobile": { "type": "array", "description": "Unique count of customers with mobile activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "woocommerce": { "type": "array", "description": "Unique count of customers with woocommerce activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } }, "onlineStore": { "type": "array", "description": "Unique count of customers with online store activities", "items": { "$ref": "#/components/schemas/CustomerDataPoint" } } } }, "UpdatedAt": { "type": "object", "required": [ "updatedAt" ], "properties": { "updatedAt": { "description": "The datetime that the customer was last updated. Required on update calls and used for optimistic concurrency: pass back the `updatedAt` from your most recent GET. A **stale** `updatedAt` still returns a 202 but the update is silently dropped — re-GET the customer and retry with the fresh value if the change did not take effect.\n", "$ref": "#/x-ext/37bf2ab" } } }, "Url": { "required": [ "url" ], "properties": { "url": { "description": "A url associated with the customer", "type": "string", "format": "url", "maxLength": 2083 }, "label": { "description": "A user provided name for the url", "type": "string", "maxLength": 255 } }, "type": "object" }, "Error": { "x-error-model": true, "type": "object", "description": "Generic application-level error envelope returned for non-validation failures (401, 403, 404, 409, 429, 5xx).\n\nTwo `code` fields are emitted side-by-side:\n\n- `code` (lowercase snake_case) is preserved for backwards compatibility, e.g. `customer_not_found`, `failed_oauth_permission_check`.\n- `x-error-code` (SCREAMING_SNAKE_CASE) is the canonical identifier for client-side error handling and is the value referenced by each operation's `x-error-code` extension, e.g. `NOT_FOUND_CUSTOMER`, `MISSING_PERMISSION`. **Treat `x-error-code` as the contract.**\n\nValidation errors (HTTP 422) use the `ValidationError` schema instead.\n", "properties": { "code": { "type": "string", "description": "Lowercase snake_case identifier for the error. Preserved for backwards compatibility." }, "x-error-code": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*$", "description": "SCREAMING_SNAKE_CASE identifier suitable for client-side error handling." }, "message": { "type": "string", "description": "Human-readable, English description of the error." } }, "required": [ "code", "x-error-code", "message" ] }, "ValidationError": { "x-error-model": true, "type": "object", "description": "Error envelope returned for HTTP 422 (validation) failures.\n\n- `code` is always `BODY_DOES_NOT_FULFILL_SCHEMA`.\n- `errorCode` is a deprecated alias of `code`. Will be removed once integrators migrate.\n- Per-field validation errors are returned in the `fields` array.\n", "required": [ "message", "code", "fields" ], "properties": { "message": { "type": "string", "description": "Human-readable summary of the failure (currently always `\"Body does not fulfill the schema\"`)." }, "code": { "type": "string", "description": "Always `BODY_DOES_NOT_FULFILL_SCHEMA` for 422 responses from these endpoints.", "enum": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ] }, "errorCode": { "type": "string", "deprecated": true, "description": "Deprecated alias of `code`. Always equals `code` when present." }, "fields": { "type": "array", "minItems": 1, "description": "One entry per field-level validation failure.", "items": { "$ref": "#/components/schemas/ErrorField" } } } }, "ErrorLimit": { "x-error-model": true, "additionalProperties": false, "allOf": [ { "type": "object", "properties": { "retryAfterSec": { "type": "integer", "format": "integer-positive", "pattern": "^[0-9]+$", "description": "Number of seconds to wait before attempting a similar request" } }, "required": [ "retryAfterSec" ] }, { "$ref": "#/components/schemas/Error" } ], "type": "object" }, "ErrorField": { "type": "object", "properties": { "path": { "type": "string", "format": "json-path", "description": "JSONPath referring to the field within the request body that failed validation, e.g. `$.source` for a top-level field, `$.customer.emails[0]` for a nested array element.\n", "examples": [ "$.source" ] }, "pathRelated": { "type": "string", "format": "json-path", "description": "Optional. When `path` resolves to an object (rather than a leaf value), `pathRelated` points at the specific property on that object that failed validation. For example, given `path: $.customer.emails[0]`, a `pathRelated: $.email` indicates the `email` property of the indexed array element is invalid.\n", "examples": [ "$.email" ] }, "code": { "type": "string", "description": "Lowercase identifier for the field-level validation failure, sourced from the underlying validator (e.g. `blank`, `invalid`, `taken`, `inclusion`). NOT a SCREAMING_SNAKE_CASE error code; for that, branch on the top-level `code` of the parent `ValidationError` envelope.\n" }, "message": { "type": "string", "description": "Human-readable description of the field-level error, e.g. `\"source can't be blank\"`." } }, "required": [ "path", "code", "message" ] }, "ErrorWithId": { "x-error-model": true, "allOf": [ { "type": "object", "properties": { "errorId": { "type": "string", "description": "Unique identifier for this specific error instance" } }, "required": [ "errorId" ] }, { "$ref": "#/components/schemas/Error" } ] } }, "parameters": { "customerId": { "name": "customerId", "description": "The id of the specific customer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "customerListKey": { "name": "customerListKey", "description": "The key of the specific Customer List", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "page": { "name": "page", "in": "query", "required": false, "description": "The page of results to return for pagination. Only supported up to the first 10 000 records of a result set. Use pageToken rather than page where possible. PageToken and page can not be used in combination, doing so will result in a 422 response.", "schema": { "type": "integer", "format": "integer-positive", "default": 1 } }, "pageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Maximum number of items to return. If used with page will return results with an offset of page * pageSize", "schema": { "type": "integer", "format": "integer-positive", "default": 25, "maximum": 500 } }, "pageToken": { "name": "pageToken", "in": "query", "required": false, "description": "Use the `pageToken` returned from a previous search in order to obtain the next set of results. Use pageToken rather than page where possible. PageToken and page can not be used in combination, doing so will result in a 422 response.", "schema": { "type": "string" } }, "periodStartedAt": { "name": "periodStartedAt", "required": false, "in": "query", "description": "Start of range indicating what time-frame should be returned", "schema": { "$ref": "#/x-ext/37bf2ab" } }, "periodEndedAt": { "name": "periodEndedAt", "required": false, "in": "query", "description": "End of range indicating what time-frame should be returned", "schema": { "$ref": "#/x-ext/37bf2ab" } }, "storeId": { "name": "storeId", "required": true, "in": "path", "description": "An identifier for a store", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "400": { "description": "Query string and/or request body are malformed", "x-error-code": [ "MALFORMED_INPUT" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication info not sent or is invalid", "x-error-code": [ "UNAUTHORIZED" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated user is not allowed access", "x-error-code": [ "ACCESS_DENIED" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "x-error-code": [ "NOT_FOUND" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Application-specific server state error", "x-error-code": [ "CONFLICTING_STATUS" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Body or query string failed schema validation. Returns the `ValidationError` envelope rather than the generic `Error`.", "x-error-code": [ "BODY_DOES_NOT_FULFILL_SCHEMA" ], "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests received within interval", "x-error-code": [ "RATE_LIMITED" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorLimit" } } } }, "500": { "description": "Internal server error", "x-error-code": [ "INTERNAL_SERVER_ERROR" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service is temporarily unavailable", "x-error-code": [ "SERVICE_UNAVAILABLE" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Gateway timeout", "x-error-code": [ "GATEWAY_TIMEOUT" ], "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "PAT": { "type": "http", "scheme": "bearer", "description": "Personal Access Token (PAT). Include as `Authorization: Bearer $GODADDY_PAT`. Required scopes: `commerce.customer:read`, `commerce.customer:create`, `commerce.customer:update`." } } }, "x-ext-urls": { "37bf2ab": "common-types/v1/schemas/yaml/date-time.yaml", "590647a": "common-types/v1/schemas/yaml/link-description.yaml", "4945a71": "common-types/v1/schemas/yaml/email-address.yaml" }, "x-ext": { "37bf2ab": { "description": "A date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Note: The regular expression provides static schematic guidance but does not reject all invalid dates.", "type": "string", "minLength": 20, "maxLength": 64, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$" }, "590647a": { "title": "Link Description", "type": "object", "description": "A request-related [HATEOAS link](https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02).", "properties": { "href": { "description": "The complete target URL, or link, to use in combination with the method to make the related call, as defined by [RFC 6570 - URI Template](https://tools.ietf.org/html/rfc6570), with the addition of the `$`, `(`, and `)` characters for pre-processing. The `href` is the key HATEOAS component that links a completed call with a subsequent call.", "type": "string", "format": "uri" }, "rel": { "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which is an identifier for a link that unambiguously describes the semantics of the link. For values, see [Link Relationship Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml).", "type": "string" }, "title": { "description": "The link title.", "type": "string" }, "targetMediaType": { "description": "The [RFC 2046-defined media type](https://www.ietf.org/rfc/rfc2046.txt) that describes the link target.", "type": "string" }, "targetSchema": { "description": "The schema that describes the link target." }, "method": { "description": "The method to use to request the link target. For example, for HTTP, this might be `GET` or `DELETE`.", "type": "string" }, "submissionMediaType": { "description": "The media type with which to submit data with the request.", "type": "string", "default": "application/json" }, "submissionSchema": { "description": "The schema that describes the request data." } }, "required": [ "rel", "href" ] }, "4945a71": { "description": "A valid, internationalized email address. Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.", "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" } } }