{ "openapi": "3.1.1", "info": { "title": "Commerce Store API", "version": "2.1.0", "description": "This API is capable of recording, updating and retrieving store information.\n\n> **Deployment status:** the v2 namespace is not yet deployed at the gateway.\n> Callers should use `/v1/commerce/` until v2 routing ships." }, "servers": [ { "url": "https://api.godaddy.com/v1/commerce", "description": "Production" } ], "components": { "parameters": { "businessId": { "name": "businessId", "description": "Business ID", "schema": { "$ref": "#/x-ext/06c64a5" }, "in": "query", "required": true }, "storeId": { "name": "storeId", "description": "Store ID", "schema": { "$ref": "#/x-ext/06c64a5" }, "in": "path", "required": true }, "storeIdParam": { "name": "storeId", "description": "Store ID", "schema": { "$ref": "#/x-ext/06c64a5" }, "in": "query", "required": true }, "attrName": { "name": "attrName", "description": "Attribute name", "schema": { "type": "string" }, "in": "path", "required": true }, "requestId": { "name": "X-Request-Id", "description": "Request ID", "in": "header", "schema": { "type": "string", "format": "uuid" } }, "ifModifiedSince": { "name": "If-Modified-Since", "description": "To check if data has been modified since a given date", "in": "header", "schema": { "type": "string", "format": "date-time" } }, "pageSize": { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 10 } }, "page": { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, "totalRequired": { "name": "totalRequired", "in": "query", "schema": { "type": "boolean", "default": false } }, "includeFields": { "name": "includeFields", "in": "query", "description": "Optional joins to fold into the response. Additive on top of the default\nfield set, not a replacement filter — fields outside this enum are returned\nunconditionally. Comma-separate values to request multiple joins.\n\nNote: the live (v1) gateway exposes this parameter as `includeField`\n(singular) and accepts repeated parameters. The v2 spelling here is the\ntarget shape for when v2 ships.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "phone", "address", "attributes", "storeAttributes", "paymentAttributes", "storeDevice", "storeTerminalId", "storeTerminalIdAllVTAndFirstActivated", "processorData", "processorDataNonSensitive", "businessAgreement", "subscribedBundles" ] } }, "examples": { "default": { "value": "address,attributes" } } } }, "schemas": { "governmentIdList": { "type": "array", "items": { "$ref": "#/x-ext/d7e1a1f" } }, "attributeUpdateRequest": { "properties": { "value": { "type": "string", "description": "The attribute value." }, "ttl": { "type": "integer", "description": "The expiration time of an ephemeral attribute." } }, "required": [ "value" ], "type": "object" } }, "headers": { "X-Request-Id": { "description": "Request Id", "deprecated": true, "schema": { "type": "string", "format": "uuid" } }, "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Location of the resource" } }, "responses": { "200": { "description": "Request was successful", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "201": { "description": "New resource created successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Location": { "$ref": "#/components/headers/Location" } } }, "error": { "description": "Error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/x-ext/852136a" } } } } }, "securitySchemes": { "PAT": { "type": "http", "scheme": "bearer", "description": "Personal Access Token (PAT). Include as `Authorization: Bearer $GODADDY_PAT`. Required scopes: `commerce.store:read`." } } }, "tags": [ { "name": "Store", "description": "Read stores and store attributes." } ], "paths": { "/stores/{storeId}": { "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "$ref": "#/components/parameters/storeId" }, { "$ref": "#/components/parameters/includeFields" } ], "get": { "operationId": "getStoreById", "description": "Retrieve the information of a store using the Business and Store IDs.", "summary": "Get store by ID", "tags": [ "Store" ], "responses": { "200": { "description": "Store Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/x-ext/4ba7beb" }, "examples": { "default": { "value": { "id": "a4935421-1995-4b11-8cc3-99c6ad404007", "businessId": "02a17e5b-0897-4d39-9123-b4345163e6df", "displayName": "Global Ventures Apr 22133824", "status": "ACTIVE", "currency": "USD", "timezone": "America/Los_Angeles", "acquirer": "WORLDPAY", "processor": "WORLDPAY", "externalStoreId": "wp-retail-ce5ecce4", "processorData": {}, "attributes": {}, "fixedLocation": true, "mockProcessor": true, "longitude": -122.162, "latitude": 37.4457, "defaultChannelId": "64bdf0cc-02d1-4326-b24e-9e611afc729f", "defaultRetailChannelId": "c884df62-6c3b-4df0-81b7-80b8c4b73bcf", "ownerId": "22264b76-d57b-4eb3-ab4e-1dbe5aeaeed1", "createdAt": "2026-04-22T08:10:26Z", "updatedAt": "2026-04-22T08:10:37Z" } } } } } }, "default": { "$ref": "#/components/responses/error" } }, "security": [ { "PAT": [ "commerce.store:read" ] } ] } }, "/stores/{storeId}/attributes/{attrName}": { "parameters": [ { "$ref": "#/components/parameters/requestId" }, { "$ref": "#/components/parameters/storeId" }, { "$ref": "#/components/parameters/attrName" } ], "get": { "operationId": "getStoreAttribute", "description": "Look up a single store attribute by name. Response shape is a\nsingle-key map of `{: }` — values are always strings.\nAllow-listed keys that have not been set return 404\n`BUSINESS_ATTRIBUTE_NOT_FOUND`; keys outside the per-store allow-list\nreturn 400 `INVALID_REQUEST`.", "summary": "Get store attribute", "tags": [ "Store" ], "responses": { "200": { "description": "Store Attribute Found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "description": "Single-key map of attribute name → value (value is always a string).", "additionalProperties": { "type": "string" }, "examples": [ { "settlementRiskBlockOverride": "true" } ] } } } }, "400": { "description": "Attribute key is not in the store's allow-list." }, "404": { "description": "Store Or Store Attribute Not Found" }, "default": { "$ref": "#/components/responses/error" } }, "security": [ { "PAT": [ "commerce.store:read" ] } ] } } }, "x-ext-urls": { "06c64a5": "common-types/v1/uuid.json", "d7e1a1f": "models/GovernmentId.yaml", "852136a": "common-types/v1/error.json", "79cf1fe": "common-types/v1/error-details.json", "f5d75d5": "common-types/v1/link-description.json", "4ba7beb": "models/Store.yaml", "b07c316": "models/Processor.yaml", "7fe15e4": "common-types/v1/address.json", "8be89e0": "common-types/v1/country-code.json", "c87e5c5": "common-types/v1/geo-coordinates.json", "cb01ff4": "types/Dictionary.yaml", "65e4b88": "common-types/v1/currency-code.json", "15843ae": "types/PhoneWithType.yaml", "64613c3": "common-types/v1/phone.json", "a0df9cc": "common-types/v1/phone-type.json", "a9bfdca": "models/BundledFeatures.yaml" }, "x-ext": { "06c64a5": { "description": "A universally unique identifier (UUID) in [RFC-4122 format](https://tools.ietf.org/html/rfc4122).", "type": "string", "format": "uuid" }, "d7e1a1f": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "GovernmentId", "description": "GovernmentId details", "type": "object", "properties": { "createdAt": { "type": "string", "description": "The time (in ISO-8601 format) at which the application was created. E.g. 2014-09-11T23:14:44Z.", "format": "date-time", "readOnly": true }, "governmentId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The government id. E.g. '123456789'" }, "type": { "type": "string", "enum": [ "EIN", "SSN" ], "description": "The type of government id. Only the values listed in the enum are accepted by the live API.", "examples": [ "EIN" ] }, "updatedAt": { "type": "string", "description": "The time (in ISO-8601 format) at which the application was updated. E.g. 2014-09-11T23:14:44Z.", "format": "date-time", "readOnly": true } }, "required": [ "governmentId", "type" ] }, "79cf1fe": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "The field that caused the error. If the field is in the body, set this value to the JSON pointer to that field. Required for client-side errors." }, "value": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "default": "body" }, "issue": { "type": "string", "description": "The unique fine-grained application-level error code." }, "description": { "type": "string", "description": "The human-readable description for an issue. The description MAY change over the lifetime of an API, so clients MUST NOT depend on this value." } }, "required": [ "issue" ] }, "f5d75d5": { "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" ] }, "852136a": { "type": "object", "title": "Error", "description": "The error information.", "definitions": { "error-details": { "$ref": "#/x-ext/79cf1fe" }, "link-description": { "$ref": "#/x-ext/f5d75d5" } }, "properties": { "name": { "type": "string", "description": "The human-readable, unique name of the error." }, "correlationId": { "type": "string", "description": "Internal identifier used for correlation purposes." }, "message": { "type": "string", "description": "The message that describes the error." }, "informationLink": { "type": "string", "description": "The URI for detailed information related to this error for the developer." }, "details": { "type": "array", "description": "An array of additional details about the error. Required for client-side `4XX` errors.", "additionalItems": false, "items": { "$ref": "#/x-ext/852136a/definitions/error-details" } }, "links": { "type": "array", "description": "An array of error-related HATEOAS links.", "readOnly": true, "items": { "$ref": "#/x-ext/852136a/definitions/link-description", "readOnly": true } } }, "required": [ "name", "correlationId", "message" ] }, "b07c316": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Store Processor", "description": "Processor to be used by Store", "type": "string", "enum": [ "CHASE_PAYMENTECH", "REDE", "EVO", "FIRST_DATA", "GLOBAL_PAYMENTS", "HEARTLAND_PAYMENT_SYSTEM", "ELAVON", "MERCURY", "MONERIS", "PAYPAL", "ELAVON_MX", "STRIPE", "TSYS", "VANTIV", "WORLDPAY", "EPX", "WEPAY", "MASHREQ", "AXIS", "KARTUKU", "NEXI", "DANA", "MYNT", "POYNT", "NUVEI", "NPAY", "BRIDGEPAY", "CONVERGE", "MOCK", "NA_BANCARD", "CREDITCALL", "ELAVON_EU", "FUSEBOX", "EVERTEC", "GHL", "RS2", "JCN", "PRISMA", "VANTIV_EXPRESS", "EZETAP", "ADYEN", "USBANK", "LETGO", "CHECK_COMMERCE" ] }, "8be89e0": { "description": "A two-character ISO 3166-1 code that identifies the country or region.", "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "c87e5c5": { "type": "object", "title": "Geographic Coordinates", "description": "The geographic latitude and longitude coordinates.", "properties": { "longitude": { "type": "string", "pattern": "^-?([1]?[1-7][1-9]|[1]?[1-8][0]|[1-9]?[0-9])\\.{1}\\d{1,6}" }, "latitude": { "type": "string", "pattern": "^-?([1-8]?[1-9]|[1-9]0)\\.{1}\\d{1,6}" } }, "required": [ "longitude", "latitude" ] }, "7fe15e4": { "type": "object", "title": "Postal Address (Medium-Grained)", "description": "An internationalized postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) from Google's Address Data Service and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).", "properties": { "addressLine1": { "type": "string", "description": "The first line of the address. For example, number and street name. For example, `3032 Bunker Hill Lane`. Required for compliance and risk checks. Must contain the full address.", "maxLength": 300 }, "addressLine2": { "type": "string", "description": "The second line of the address. For example, office suite or apartment number.", "maxLength": 300 }, "addressLine3": { "type": "string", "description": "The third line of the address, if needed. For example, a street complement for Brazil; direction text, such as `next to Opera House`; or a landmark reference in an Indian address.", "maxLength": 100 }, "adminArea4": { "description": "The neighborhood, ward, or district. Smaller than `adminArea3` or `subLocality`. For example, the postal sorting code that is used in Guernsey and many French territories, such as French Guiana; the fine-grained administrative levels in China.", "type": "string", "maxLength": 100 }, "adminArea3": { "description": "A sub-locality, suburb, neighborhood, or district. Smaller than `adminArea2`. For example, in Brazil - Suburb, bairro, or neighborhood; in India - Sub-locality or district. Street name information may not always be available and a sub-locality or district can reference a very small area.", "type": "string", "maxLength": 100 }, "adminArea2": { "description": "A city, town, or village. Smaller than `adminArea1`.", "type": "string", "maxLength": 300 }, "adminArea1": { "type": "string", "description": "The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision; formatted for postal delivery. For example, `CA` and not `California`. For example, for UK - A county; for the US - A state; for Canada - A province; for Japan - A prefecture; for Switzerland - A canton.", "maxLength": 300 }, "postalCode": { "type": "string", "description": "The postal code, which is the zip code or equivalent. Typically required for countries that have a postal code or an equivalent. See [Postal code](https://en.wikipedia.org/wiki/Postal_code).", "maxLength": 60 }, "countryCode": { "$ref": "#/x-ext/8be89e0", "description": "The [two-character ISO 3166-1 code](https://en.wikipedia.org/wiki/ISO_3166-1) that identifies the country or region. Note: The country code for Great Britain is `GB` and not `UK` as used in the top-level domain names for that country. Use country code `C2` for China for comparable uncontrolled price (CUP) method, bank-card, and cross-border transactions." }, "addressDetails": { "type": "object", "title": "Address Details", "description": "The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grained address information might be needed. Not portable with common third-party and open-source address libraries and redundant with core fields. For example, `address.addressLine1` is usually a combination of `addressDetails.streetNumber` and `streetName` and `streetType`.", "properties": { "streetNumber": { "description": "The street number.", "type": "string", "maxLength": 100 }, "streetName": { "description": "The street name. Just `Drury` in `Drury Lane`.", "type": "string", "maxLength": 100 }, "streetType": { "description": "The street type. For example, avenue, boulevard, road, or expressway.", "type": "string", "maxLength": 100 }, "deliveryService": { "description": "The delivery service. Post office box, bag number, or post office name.", "type": "string", "maxLength": 100 }, "buildingName": { "description": "A named location that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, Craven House.", "type": "string", "maxLength": 100 }, "subBuilding": { "description": "The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.", "type": "string", "maxLength": 100 }, "addressType": { "description": "The type of address. Single character representation of a type. For example: 'B' for building, 'F' for organization, 'G' for general delivery, 'H' for high-rise, 'L' for large-volume organization, 'P' for Post Office box or delivery service, 'R' for rural route, 'S' for street, 'U' for unidentified address.", "type": "string", "maxLength": 1 }, "geoCoordinates": { "description": "The latitude and longitude of the address. For example, `37.42242` and `-122.08585`.", "$ref": "#/x-ext/c87e5c5" } } } }, "required": [ "countryCode" ] }, "cb01ff4": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Dictionary", "description": "Key value pairs of strings", "type": "object", "minProperties": 0, "maxProperties": 40, "additionalProperties": { "type": "string", "maxLength": 256 } }, "65e4b88": { "type": "string", "title": "Currency Code", "description": "A three-character ISO-4217 currency code.", "minLength": 3, "maxLength": 3 }, "64613c3": { "type": "object", "title": "Phone", "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).", "properties": { "countryCode": { "type": "string", "description": "The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "nationalNumber": { "type": "string", "description": "The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" }, "extensionNumber": { "type": "string", "description": "The extension number.", "minLength": 1, "maxLength": 15, "pattern": "^[0-9]{1,15}?$" } }, "required": [ "countryCode", "nationalNumber" ] }, "a0df9cc": { "type": "string", "title": "Phone type", "description": "The phone type.", "enum": [ "FAX", "HOME", "MOBILE", "OTHER", "WORK" ] }, "15843ae": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Phone with Type", "type": "object", "description": "Contact Phone", "properties": { "details": { "description": "Phone number details", "$ref": "#/x-ext/64613c3" }, "type": { "description": "Phone type", "$ref": "#/x-ext/a0df9cc" } }, "required": [ "details" ] }, "a9bfdca": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Bundled Features", "description": "This is the base object for the list of features a business/store has subscribed to.", "deprecated": true, "type": "object", "properties": { "createdAt": { "type": "string", "description": "This is a response only field. The time (in ISO-8601 format) at which the bundle was created. E.g. 2014-09-11T23:14:44Z.", "format": "date-time", "readOnly": true }, "featureConfig": { "$ref": "#/x-ext/cb01ff4", "description": "Optional configs for each feature in the list." }, "featureList": { "description": "List of features the bundle contains.", "maxItems": 80, "type": "array", "items": { "type": "string" } }, "id": { "$ref": "#/x-ext/06c64a5", "description": "The id of the bundle. " }, "name": { "type": "string", "description": "Name of bundle.", "maxLength": 64 }, "type": { "type": "string", "description": "The type of the bundle." }, "updatedAt": { "type": "string", "description": "This is a response only field. The time (in ISO-8601 format) at which the bundle was updated. E.g. 2014-09-11T23:14:44Z.", "format": "date-time", "readOnly": true } }, "required": [ "featureList", "id", "name" ] }, "4ba7beb": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Store", "type": "object", "properties": { "acquirer": { "allOf": [ { "$ref": "#/x-ext/b07c316" } ], "description": "The acquirer for this merchant." }, "address": { "description": "The store's address. This may or may not be different from business address.", "$ref": "#/x-ext/7fe15e4" }, "attributes": { "$ref": "#/x-ext/cb01ff4", "description": "A name/value pair list that could be persisted and later retrieved." }, "createdAt": { "type": "string", "description": "The createdAt of the store. This createdAt is generated internally during create store.", "format": "date-time", "readOnly": true }, "currency": { "$ref": "#/x-ext/65e4b88", "description": "The primary transaction currency for this merchant." }, "defaultChannelId": { "$ref": "#/x-ext/06c64a5", "description": "The default channel of the store, where uncategorized transactions are mapped to" }, "defaultRetailChannelId": { "$ref": "#/x-ext/06c64a5", "description": "The default retail channel of the store, where uncategorized transactions from terminals in retail store are mapped to" }, "displayName": { "type": "string", "description": "The store name (used in various displays). It is recommended to pick a different name for each store in the business.", "maxLength": 64 }, "emailAddress": { "type": "string", "maxLength": 64, "description": "The email address of the store." }, "externalStoreId": { "type": "string", "description": "MID (merchantId) assigned to the store by the acquirer.", "maxLength": 64 }, "fixedLocation": { "type": "boolean", "description": "Fixed location vs a mobile store (e.g. food truck).", "deprecated": true }, "governmentIds": { "maxItems": 10, "type": "array", "items": { "$ref": "#/x-ext/d7e1a1f" } }, "id": { "$ref": "#/x-ext/06c64a5", "description": "The id of the store. This id is generated internally during create business." }, "businessId": { "$ref": "#/x-ext/06c64a5", "description": "The business id the store belongs to" }, "latitude": { "type": "number", "description": "Latitude of the terminal.", "deprecated": true }, "longitude": { "type": "number", "description": "Longitude of the terminal.", "deprecated": true }, "mockProcessor": { "type": "boolean", "deprecated": true, "description": "It indicates if the store is using a mock processor." }, "phone": { "$ref": "#/x-ext/15843ae", "description": "The store's phone. This may or may not be different from business phone." }, "processor": { "allOf": [ { "$ref": "#/x-ext/b07c316" } ], "description": "The processor for this merchant. If this field is left blank it is assumed that the processor is the acquirer itself or CreditCall that happens to be our primary gateway." }, "processorData": { "allOf": [ { "$ref": "#/x-ext/cb01ff4" } ], "description": "The processor data for the store." }, "status": { "type": "string", "default": "ACTIVE", "enum": [ "ACTIVE", "DISABLED", "REMOVED" ], "description": "The status of the store." }, "subscribedBundles": { "description": "The list of bundles this store has subscribed to.", "type": "array", "items": { "$ref": "#/x-ext/a9bfdca" } }, "timezone": { "type": "string", "description": "The timezone of the store.", "maxLength": 64 }, "updatedAt": { "type": "string", "description": "The updatedAt of the store. This updatedAt is set internally during store updates.", "format": "date-time", "readOnly": true }, "ownerId": { "$ref": "#/x-ext/06c64a5", "description": "The id of the store owner." } }, "description": "Store represent a brand under a business", "required": [ "displayName", "businessId" ] } } }