{ "openapi": "3.1.1", "info": { "title": "Channels API", "version": "1.0.0", "description": "Every response echoes a request correlation ID in `Poynt-Request-Id` and `X-Request-Id`. Both headers contain the same value as the `requestId` field in error envelopes. Clients may set `Poynt-Request-Id` on incoming requests; if omitted the server generates one." }, "servers": [ { "url": "https://api.{sub-domain}.com/{version}/{namespace}", "variables": { "version": { "default": "v1", "description": "Version" }, "namespace": { "default": "commerce", "description": "Namespace" }, "sub-domain": { "default": "godaddy", "description": "Sub domain for different environments", "enum": [ "godaddy", "ote-godaddy", "test-godaddy", "dev-godaddy" ] } } } ], "components": { "securitySchemes": { "PAT": { "type": "http", "scheme": "bearer", "description": "Personal Access Token (PAT). Include as `Authorization: Bearer $GODADDY_PAT`. Required scopes: `commerce.channel:read`." } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Location of the resource" }, "Poynt-Request-Id": { "schema": { "type": "string" }, "description": "Echoed (or server-generated) request correlation ID. Matches the value in the `requestId` field of error envelopes and the `X-Request-Id` response header. Present on every observed response." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Same value as `Poynt-Request-Id`; present on every observed response." } }, "responses": { "BadRequest": { "description": "Invalid request (validation error or missing required parameter).", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } }, "Unauthorized": { "description": "Authentication failed or missing.", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } }, "Forbidden": { "description": "Caller is authenticated but not authorized for this action.", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } }, "Conflict": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } }, "InternalServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/x-ext/e2dac50" } } } } } }, "tags": [ { "name": "Channel", "description": "Read sales channels." } ], "paths": { "/channels": { "get": { "x-internal": true, "x-must-have-one-of": [ "registeredStores.storeId", "externalChannelId" ], "description": "**Internal API.** Intended for platform-internal callers. Access requires a service principal with the `GLOBAL` resource group, or a customer with `COMMERCE_STORE` access scoped via `registeredStores.storeId`. Calling with only `externalChannelId` (no `storeId`) yields `401` for customer principals.\n\nRetrieve all the channels for a specific provider using parameters. At least one of `registeredStores.storeId` or `externalChannelId` must be provided — calling without either yields `400 INVALID_REQUEST` with `developerMessage=\"Either storeId or externalChannelId is required\"`. Note: the error message says `storeId` but the actual query parameter name is `registeredStores.storeId`.", "summary": "Get all channels", "parameters": [ { "in": "query", "name": "externalChannelId", "schema": { "type": "string" } }, { "in": "query", "name": "registeredStores.storeId", "schema": { "$ref": "#/x-ext/f172461" } }, { "in": "query", "name": "registeredStores.default", "schema": { "type": [ "boolean", "null" ] } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "maximum": 100 } }, { "name": "totalRequired", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When `true`, the response includes `totalItems`, `totalPages`, and a `last` HATEOAS link. When `false` (default), those fields and the `last` link are omitted." } ], "tags": [ "Channel" ], "operationId": "getChannels", "security": [ { "PAT": [ "commerce.channel:read" ] } ], "responses": { "200": { "description": "Channels", "content": { "application/json": { "schema": { "$ref": "#/x-ext/b8a4d41" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/channels/{channelId}": { "parameters": [ { "schema": { "$ref": "#/x-ext/f172461" }, "name": "channelId", "in": "path", "required": true } ], "get": { "description": "Retrieve the information of a single channel using the Channel ID. Access requires a relation against the specific Channel resource (for example, a service principal in `GLOBAL`, or a customer with channel-scoped permissions). A customer with read access to the parent store can still see a channel via `GET /channels?registeredStores.storeId=...` when this get-by-id call returns `401`. Authorization is checked before existence, so an unknown `channelId` may return `401` instead of `404`.", "summary": "Get channel by ID", "tags": [ "Channel" ], "responses": { "200": { "description": "Channel Found", "content": { "application/json": { "schema": { "$ref": "#/x-ext/df5646b" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "operationId": "getChannelById", "security": [ { "PAT": [ "commerce.channel:read" ] } ] } } }, "x-ext-urls": { "e2dac50": "common-types/error.json", "f172461": "types/Id.yaml", "b8a4d41": "models/ChannelList.yaml", "df5646b": "models/Channel.yaml", "73eb213": "enums/ChannelType.yaml", "984fcda": "enums/ChannelStatus.yaml", "7aa56da": "models/RegisteredStore.yaml", "cc01438": "enums/RegisteredStoreStatus.yaml", "8f1f45d": "types/Links.yaml", "3eae49a": "common-types/link-description.json", "3652e93": "common-types/date-time.json", "562f832": "models/RetailLocation.yaml", "3ce5bda": "common-types/address.json", "424ba95": "common-types/country-code.json", "cf8c911": "common-types/geo-coordinates.json", "483e4a9": "models/RetailLocationContact.yaml", "ebf481b": "common-types/phone-type.json", "b9df754": "common-types/phone.json" }, "x-ext": { "e2dac50": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "title": "Error", "description": "Standard error envelope returned for non-2xx responses. Verified live across responses 01, 04(b), 05, 07-16: every observed error body is exactly `{code, httpStatus, message, developerMessage, requestId}`. The `moreInfo` field was NOT present in any observed error and is modeled as optional.", "properties": { "code": { "type": "string", "description": "A short, machine-readable error code (e.g. UNAUTHORIZED_ACCESS, INVALID_REQUEST, INVALID_PARAMETER). Verified live." }, "httpStatus": { "type": "integer", "description": "The HTTP status code associated with the error. Verified live (matches the response status)." }, "message": { "type": "string", "description": "A human-readable description of the error suitable for display." }, "developerMessage": { "type": "string", "description": "Additional detail aimed at developers integrating the API. Caution: response 16 shows the impl can leak Java framework exception text here (e.g. 'java.lang.IllegalArgumentException: Invalid UUID string: ...'); see SB5." }, "moreInfo": { "type": [ "string", "null" ], "description": "Optional URL or text pointing to documentation or further detail. Not observed in any live response — included for forward compatibility only." }, "requestId": { "type": [ "string", "null" ], "description": "Identifier of the request that produced the error, used for correlation in logs. Live behavior: this field is present on every observed error response and matches the `poynt-request-id` / `x-request-id` echo headers." } }, "required": [ "code", "httpStatus", "message", "developerMessage", "requestId" ] }, "f172461": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Id", "description": "unique identifier", "type": "string", "format": "uuid", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "examples": { "default": { "value": "410dee2e-abbf-3f59-b640-fc3aca175344" } } }, "73eb213": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ChannelType", "type": "string", "description": "ChannelType", "enum": [ "RETAIL", "ONLINE", "MOBILE", "MARKETPLACE", "SOCIAL", "DEFAULT" ] }, "984fcda": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ChannelStatus", "type": "string", "description": "Channel Status", "enum": [ "PENDING_SETUP", "ACTIVE", "INACTIVE", "ERROR", "REMOVED" ], "default": "ACTIVE" }, "cc01438": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "RegisteredStoreStatus", "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "Registered Store Status", "default": "ENABLED" }, "3eae49a": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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" ] }, "8f1f45d": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Links", "description": "HATEOAS links", "type": "array", "items": { "$ref": "#/x-ext/3eae49a" } }, "3652e93": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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})$" }, "7aa56da": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "RegisteredStore", "type": "object", "description": "Resource representing Store registration with Channel", "properties": { "storeId": { "$ref": "#/x-ext/f172461", "description": "Id of the store that can be used to reference" }, "status": { "description": "Status of the registration", "$ref": "#/x-ext/cc01438" }, "default": { "type": "boolean", "description": "If this is a default channel for the store", "default": false }, "links": { "description": "Links pointing to external resource", "$ref": "#/x-ext/8f1f45d", "readOnly": true }, "createdAt": { "$ref": "#/x-ext/3652e93", "description": "The date and time the store registration was created.", "readOnly": true }, "updatedAt": { "$ref": "#/x-ext/3652e93", "description": "The date and time the store registration was updated.", "readOnly": true } }, "required": [ "storeId" ] }, "424ba95": { "$schema": "http://json-schema.org/draft/2020-12/schema", "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)$" }, "cf8c911": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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" ] }, "3ce5bda": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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 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 USs - A state; for Canada - A province; for Japan - A prefecture; for Switzerland - A kanton.", "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/424ba95", "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-grain 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 locations 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/cf8c911" } } } }, "required": [ "countryCode" ] }, "ebf481b": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "title": "Phone type", "description": "The phone type.", "enum": [ "FAX", "HOME", "MOBILE", "OTHER", "WORK" ] }, "b9df754": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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" ] }, "483e4a9": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Retail Location Contact", "type": "object", "description": "Contact entry attached to a retail location.", "properties": { "type": { "description": "Type of the contact phone", "$ref": "#/x-ext/ebf481b" }, "phone": { "description": "Phone number details", "$ref": "#/x-ext/b9df754" } } }, "562f832": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Retail Location", "type": "object", "description": "Retail Location", "properties": { "alias": { "type": "string", "maxLength": 128, "description": "Alias for the location" }, "address": { "$ref": "#/x-ext/3ce5bda", "description": "Physical address of the retail location" }, "contacts": { "type": "array", "description": "Contact details of the location", "items": { "$ref": "#/x-ext/483e4a9" } } } }, "df5646b": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Channel", "type": "object", "description": "Resource representing the Channel. Note: previous revisions of this spec modeled Channel as a `oneOf` of subtypes (Retail/Online/Mobile/Marketplace/ Social/Basic) with a `type` discriminator. The implementation does not produce subtype shapes — the wire model is a single flat schema with an optional `location` field, sourced from `api-model-generator/api-model-schema/channel/Channel.json`.", "properties": { "channelId": { "$ref": "#/x-ext/f172461", "description": "Globally unique Id of the channel that can be used to reference. Cannot be patched.", "readOnly": true }, "name": { "type": "string", "description": "Name of the channel", "minLength": 1, "maxLength": 128 }, "type": { "$ref": "#/x-ext/73eb213", "description": "The type of channel. Cannot be patched (PATCH against this field is rejected by the impl).", "readOnly": true }, "channelProviderId": { "$ref": "#/x-ext/f172461", "description": "Identifier of the channel provider (defaulted based on the caller's auth credentials)" }, "externalChannelId": { "type": "string", "description": "External identifier of the channel", "minLength": 1, "maxLength": 64 }, "subType": { "type": "string", "description": "Additional information that represents the type of the channel", "maxLength": 256 }, "status": { "$ref": "#/x-ext/984fcda" }, "registeredStores": { "description": "List of stores that are registered to this channel", "type": "array", "maxItems": 50, "items": { "$ref": "#/x-ext/7aa56da" } }, "location": { "$ref": "#/x-ext/562f832", "description": "Retail channel location. Spec note: in the spec this used to be restricted to `RetailChannel` only via discriminator. The impl returns `location` whenever the underlying Channel has it stored, regardless of `type`, so it is modeled here as an optional top-level field." }, "links": { "description": "Links pointing to external resource", "$ref": "#/x-ext/8f1f45d", "readOnly": true }, "createdAt": { "$ref": "#/x-ext/3652e93", "description": "The date and time the channel was created. Cannot be patched.", "readOnly": true }, "updatedAt": { "$ref": "#/x-ext/3652e93", "description": "The date and time the channel was updated.", "readOnly": true } }, "required": [ "name", "type" ] }, "b8a4d41": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ChannelList", "type": "object", "description": "Resource representing a list of Channels", "properties": { "items": { "description": "Array containing the current page of Channels", "items": { "$ref": "#/x-ext/df5646b" }, "type": "array" }, "totalItems": { "description": "Total number of Channels matching the search criteria. Conditional — present only when the request was made with `totalRequired=true`; omitted otherwise. Verified live: present in response 17 (totalRequired=true); absent in responses 04 and 18 (default and totalRequired=false).", "type": "integer" }, "totalPages": { "description": "Total number of pages matching the search criteria. Conditional — present only when the request was made with `totalRequired=true`; omitted otherwise. Same behavior as `totalItems`.", "type": "integer" }, "links": { "description": "Array of HATEOAS link relations that should be used to navigate across pages of Channels", "$ref": "#/x-ext/8f1f45d" } } } } }