Shopify Integration API used by the Talon.One Shopify app to update customer sessions and customer profiles from a Shopify storefront, authenticated with a Shopify Customer Account API token or a Shopify JWT. Served from the dedicated Talon.One host https://shopify-integration.europe-west1.talon.one.
openapi: 3.0.0
info:
version: 1.0.0
title: Shopify Integration API
description: |
Use this API to integrate with Shopify. For more information, see the [Shopify](https://docs.talon.one/docs/dev/technology-partners/shopify/integrating-with-shopify)
section in the developer docs.
servers:
- url: https://shopify-integration.europe-west1.talon.one
tags:
- name: Customer profiles
description: Use the following endpoints to manage customer data.
- name: Session
description: Use the following endpoints to manage customer sessions.
paths:
/api/v1/customer:
get:
summary: Retrieve customer data (Headless stores)
description: |
Fetches the Talon.One customer profile for a Shopify customer in a [headless store](https://shopify.dev/docs/storefronts/headless/getting-started). The response is also stored in a customer metafield in Shopify.
The response schema is identical to the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint of the Integration API.
If you call this endpoint repeatedly with the same customer access token, the endpoint sends a cached response for the given customer. The cache clears after 10 seconds. This is done to reduce data load.
operationId: getCustomerHeadless
tags:
- Customer profiles
security:
- ShopifyCustomerAccessToken: []
parameters:
- $ref: '#/components/parameters/ShopifyShopDomain'
responses:
'200':
description: OK. For details, see the response of the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingShopDomainHeader:
summary: Missing X-Shopify-Shop-Domain header
value:
success: false
message: missing X-Shopify-Shop-Domain header
InvalidConfig:
summary: Missing `api_url` or `api_key` in the config
value:
success: false
message: Invalid config
'401':
description: Unauthorized. Authentication failed or token does not grant access for the requested store.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
NoAuthHeaderOrMalformed:
summary: Missing or malformed Authorization header
value:
success: false
message: Unauthorized
ShopIdMismatch:
summary: Token's shop ID does not match the configured shop ID for the given X-Shopify-Shop-Domain
value:
success: false
message: Unauthorized
'403':
description: Forbidden. The provided token is invalid, expired, or does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidJWT:
summary: Invalid or expired JWT token
value:
success: false
message: Invalid JWT token
'404':
description: Not found. The requested resource (config or customer) could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ConfigNotFound:
summary: Configuration not found
value:
success: false
message: Config not found
CustomerNotFoundInT1:
summary: Customer profile not found
value:
success: false
message: Customer not found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InternalServerError:
summary: Internal Server Error
value:
success: false
message: Internal Server Error
/api/v1/customer-profile:
get:
summary: Retrieve customer data (Theme-based stores)
description: |
Fetches the Talon.One customer profile for a Shopify customer in a [theme-based store](https://shopify.dev/docs/storefronts/themes). The response is also stored in a customer metafield in Shopify.
The response schema is identical to the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint of the Integration API.
If you call this endpoint repeatedly with the same customer JWT token, the endpoint sends a cached response for the given customer. The cache clears after 10 seconds. This is done to reduce data load.
operationId: getCustomerThemeBased
tags:
- Customer profiles
security:
- ShopifyJWT: []
responses:
'200':
description: OK. For details, see the response of the [List customer data](https://docs.talon.one/integration-api#tag/Customer-profiles/operation/getCustomerInventory) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidConfig:
summary: Missing `api_url` or `api_key` in the config
value:
success: false
message: Invalid config
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingAuthorizationHeader:
summary: Missing Authorization header
value:
success: false
message: Unauthorized
'403':
description: Forbidden. The provided token is invalid, expired, or does not have the necessary permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidJWT:
summary: Invalid or expired JWT token. Missing required fields.
value:
success: false
message: Invalid JWT token
'404':
description: Not found. The requested resource (config or customer) could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ConfigNotFound:
summary: Configuration not found
value:
success: false
message: Config not found
CustomerNotFoundInT1:
summary: Customer profile not found
value:
success: false
message: Customer not found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InternalServerError:
summary: Internal Server Error
value:
success: false
message: Internal Server Error
/api/v1/session:
post:
summary: Create or update customer session
description: |
Creates or updates a session in Talon.One and submits Shopify cart items.
The response schema is identical to the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint of the Integration API.
operationId: upsertSession
tags:
- Session
parameters:
- $ref: '#/components/parameters/ShopifyShopDomain'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertSessionRequest'
responses:
'200':
description: OK. For details, see the response of the [Update customer session](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2) endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertSessionResponse'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
MissingShopDomainHeader:
summary: Missing X-Shopify-Shop-Domain header
value:
success: false
message: Missing X-Shopify-Shop-Domain header
MissingShopifyCartID:
summary: Missing Shopify cart ID
value:
success: false
message: id is required
MissingLineItems:
summary: Missing Shopify cart's line items
value:
success: false
message: line_items is required
MissingLineItemProperty:
summary: Missing required field in line item
value:
success: false
message: line_items[0].title is required
InvalidLineItemProperty:
summary: Line item is invalid
value:
success: false
message: line_items[0].title is not allowed to be empty
'404':
description: Not Found. The requested resource (config) could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ConfigNotFound:
summary: Configuration not found
value:
success: false
message: Config not found
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InternalServerError:
summary: Internal Server Error
value:
success: false
message: Internal Server Error
components:
schemas:
ErrorResponse:
type: object
properties:
success:
type: boolean
example: false
description: Indicates if the request was unsuccessful.
message:
type: string
description: A human-readable message describing the error.
required:
- success
- message
SuccessResponse:
type: object
required:
- success
- message
properties:
success:
type: boolean
example: true
description: Indicates if the request was successful.
message:
type: string
description: A human-readable message.
GetCustomerResponse:
type: object
properties:
profile:
type: object
description: Customer profile information.
loyalty:
type: object
description: Customer-specific information about loyalty points.
referrals:
type: array
items:
type: object
coupons:
type: array
description: The coupons reserved by this profile. This array includes hard and soft reservations. Reserved coupons also include redeemed coupons.
items:
type: object
giveaways:
type: array
items:
type: object
achievements:
type: array
items:
type: object
UpsertSessionRequest:
type: object
required:
- id
- line_items
properties:
id:
type: string
example: gid://shopify/Cart/Z2NwLXVzLWV4YW1wbGU6MDEyMzQ1Njc4OTAxMjM0NTY3ODkw?key=examplekey1234567890
description: The Shopify cart ID.
line_items:
type: array
description: The Shopify cart line items.
items:
type: object
required:
- title
- price
- quantity
description: |
A line item in the cart. The identifier for the item depends on the shop's configuration:
1. **If custom product IDs are NOT configured**: `variant_id` is REQUIRED and `custom_id` is forbidden.
2. **If custom product IDs ARE configured**: EITHER `variant_id` or `custom_id` must be provided (but not both). If only `variant_id` is sent, the backend will automatically look up the corresponding custom ID.
properties:
variant_id:
type: integer
description: The Shopify product variant ID. Required unless custom IDs are configured and `custom_id` is provided instead.
custom_id:
type: string
description: The Shopify product variant custom ID (from a metafield). If custom IDs are configured for the shop, this field can be used, but `variant_id` is preferred as the backend will perform the lookup automatically if `custom_id` is not provided.
title:
type: string
minLength: 1
price:
type: string
pattern: ^\d+(\.\d{1,2})?$
example: '18.35'
quantity:
type: integer
minimum: 1
example: 1
attributes:
type: object
description: Use this property to set a value for the attributes of your choice. Attributes represent any information to attach to your session.
UpsertSessionResponse:
type: object
GetSessionResponse:
type: object
parameters:
ShopifyShopDomain:
name: X-Shopify-Shop-Domain
in: header
required: true
description: The Shopify domain of the shop (e.g., `store.myshopify.com`).
schema:
type: string
example: store.myshopify.com
securitySchemes:
ShopifyCustomerAccessToken:
type: apiKey
in: header
name: Authorization
description: Shopify Customer Account API token (e.g., starting with "shcat_").
ShopifyJWT:
type: http
scheme: bearer
bearerFormat: JWT
description: Shopify JWT token.