Point of Sale API, SPI, and Webhook Overview

Point of Sale supports common POS workflows with APIs, SPIs, and webhooks. It provides a set of APIs for merchants to provide, update, or read data in the Point of Sale system. Backend systems hook into these APIs to complete POS integration. Point of Sale SPIs provide extensibility and the opportunity to use external systems for POS workflows.

• Environment: Used to determine URLs for OAuth2 and Point of Sale API. Possible values: Production, Staging
• Point of Sale secret: Used as header PredictSpring-Secret while calling Point of Sale API
• x-api-key: Used as header x-api-key while calling Point of Sale API
• OAuth2 client ID: Used for OAuth2 token generation
• OAuth2 client secret: Used for OAuth2 token generation

See Point of Sale SPI Error Handling.

These tables list Point of Sale API endpoints and their usage descriptions.

Create, search, update, and delete CMS users from Point of Sale.

Manage inventory in Point of Sale, including interactions related to cycle counts and receivings.

Send notifications directly to specific app users.

Create, update, and delete products in Point of Sale.

Create, update, retrieve, and delete promotions in Point of Sale.

Create, search, update, and deactivate store associates from Point of Sale.

Manage store inventory.

Create, search, retrieve, and repost orders from Point of Sale.

SPIs are outbound API calls made from Point of Sale that expect a response from the customer system and alter the behavior of the transaction journey for an associate. On the merchant side, a web server listens to this API request and handles the call. In response, Point of Sale expects a full JSON response that updates cart or customer data (for example, Clienteling API and promotion calculation).

To implement the Point of Sale SPI, provide both a staging (sandbox) environment for testing and a production environment. Requests to the SPI APIs take these forms.

https://<staging_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>

Example:

https://**staging.mycompany.com/spi**/1.0/customer/1234?api_key=ibafw4ehb2vhibdsih3vbadv

https://<production_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>

Example:

https://**www.mycompany.com/spi**/1.0/customer/1234?api_key=zmcnv9lzjkxn2vcl8nzcx

To implement the Point of Sale SPI, provide an authentication mechanism for accessing the SPI APIs with an API key. Point of Sale provides API keys (one for staging and one for production) to validate, and all SPI API requests contain an api_key request parameter.

If an invalid API key is supplied, the API responds with a 401 Unauthorized response containing an empty response body.

Sample Request with Authentication

1GET /customer/1234?api_key={API_KEY}

Sample Authentication Failure Response

1HTTP/1.1 401 Unauthorized
2{ }

1. In CMS, go to Store Management | Integrations | Custom Connectors.
2. Click Create.
3. For Connector Type, select SPI.
4. For Endpoint Name, select an endpoint. For example, CREATE_CUSTOMER.
5. Set the API Endpoint to an external endpoint for the SPI. For example, https://sample/external/endpoint/to/create/customer.
6. Select or enter the integration type. For example, HTTP_POST.
7. Set the header for the API in JSON Headers. Headers can be Content-Type or Authorization attributes (clientId or password). For example:

1Headers:{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}

Point of Sale Custom Connection supports NetSuite OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. This setup is configured directly in CMS.

1. In CMS, go to Store Management | Integrations | Custom Connectors.
2. Edit an existing configuration or create a new one.
3. Turn on NetSuite OAuth for the OAuth Config. This automatically retrieves the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

Define custom attributes to pass in a product’s SPI response. For example, when integrating with the Delivery Group SPI, define custom attributes in the spiCustomProductAttributes setting, and these attributes are included in the SPI response.

1. In CMS, go to Store Management | Store Settings | Product.
2. Go to Merchant-specific product attributes to be provided in SPI request (spiCustomProductAttributes) and enter a comma-separated list of case-insensitive attributes from the product collection (for example, variantGroupId, salePrice, manufacturer, brand).

Point of Sale automatically injects these headers when the populateNewCustomAPIHeaders toggle is enabled.

Toggle location (CMS): Store Management | Store Settings | Search Settings | Advanced | Populate New Custom API Headers

When enabled, every request to the SPI provider includes these headers:

These tables list Point of Sale SPIs and their usage descriptions.

Create, search, update, and retrieve details of a specific customer from an external system rather than from the Point of Sale system of record.

Customer Address

Used to create, search, update, and delete a customer’s address from an external system rather than from the Point of Sale system of record

Inventory

Used for retrieving inventory count of products online or in-store from an external system rather than from the Point of Sale system of record, and for reverting reserved inventory

Loyalty

Used for retrieving loyalty points redeemed in a transaction and the available rewards for a customer.

Orders

Used to retrieve, search, and export orders from an external system rather than from the Point of Sale system of record

Other

Used to verify employee status, retrieve delivery/pickup dates, validate cart, etc.

Visual Search

Used to perform visual product search by sending an image to an external recognition provider and optionally refining results with filters, sorting, and pagination

Shipping Methods

Used for receiving applicable shipping methods from an external system rather than from the Point of Sale system of record

Taxes

Used to calculate taxes, retrieve tax exemptions, and download tax rates

• For product details, there are two fields: orderProductList and productList. orderProductList contains a list of products sold, while productList is a subset (if there have been any returns or exchanges) that contains products sold with returned products and quantities removed or adjusted. For example, productList gives you the remaining products in the order that aren’t returned. If mapping to an ERP system, use orderProductList and returnProductList instead of productList to simplify the ingestion logic.
• For fulfillment details, there are two fields: omniFulfillmentType and fulfillmentType. If mapping to an ERP system for cash/carry/charge, use fulfillmentType and fulfillmentSubType instead of omniFulfillmentType.

Webhooks are outbound API calls made from Point of Sale to an external system when specified events are triggered on POS.

1. In CMS, go to Store Management | Integrations | Custom Connectors.
2. Click Create in the upper right.
3. For Connector Type, select Webhook.
4. For Endpoint Name, select an endpoint (for example, CREATE_CUSTOMER).
5. For API Endpoint, provide an external endpoint for the webhook (for example, https://sample/external/endpoint/to/create/customer).
6. For Integration Type, select or enter the type of integration (for example, HTTP_POST).
7. For JSON Headers, provide the header for the API. Headers can be Content-Type or Authorization attributes (clientId or password). For example:

1Headers:{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}

Point of Sale Custom Connection supports NetSuite OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. Configure this setup directly in CMS.

1. In CMS, go to Store Management | Integrations | Custom Connectors.
2. Edit an existing configuration or create a new one.
3. For OAuth Config, enable NetSuite OAuth. This automatically retrieves the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

You can manually repost failed webhook events in Point of Sale.

1. In CMS, go to Store Management | Reporting and Analytics | Repost Failed Webhook Events.
2. Search for the failed webhook event by configuring the search query parameters.
3. Click View Details to view the details of the payload inside the selected webhook event.
4. Click Repost to manually trigger a webhook event repost.

This table lists all available Point of Sale webhooks and their usage descriptions.

E-Receipt

Used for sending order details for email purposes

Inventory Events

Used for sending inventory data to an external system

Orders

Used for sending order posting-related data to an external system

Others

Used for sending non-categorized data (for example, void carts) to an external system

The API spec schema indicates that dates are represented with an integer data type. What is the expected date format we should use when passing dates to the API? Additionally, can you provide a sample date along with its transformed value as an example?

Dates are expected in epoch times, represented as integers (measured in milliseconds). Epoch time is the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC. See example:

• Example Date: 2023-01-15 08:30:00
• Epoch Time (in milliseconds): 1642246200000

See example with currentLoyaltyProfile.currentTier.expiryDate:

1"loyaltyProfile": {
2  "currentTier": {
3    "expiryDate": 1703782830000
4  }
5},

Can Multi-Region Feeds Be Managed Through the Product API?

The platform supports Multi-Region Feeds, allowing the primary region to run the product feed while enabling other countries to inherit the product metadata, with specific pricing and sizing data provided for each country. However, this capability doesn’t extend directly through the Product API.

• For Multi-Region Pricing Updates: There’s no dedicated pricing API. For multi-region operations, pricing updates must be conducted through the CMS feed mechanism, allowing for regional-level adjustments.

• For Single-Region Pricing Updates: In a single-region setup, the Product API can update pricing information. However, for multi-region scenarios, the Product API lacks a region field in its specifications (as observed in this guide).

• Workaround for Pricing Updates: Given the absence of a pricing API, pricing information must be included within POST and PUT calls when managing product data. If operating with a single instance per region, the Product API can facilitate pricing updates effectively.

Do you offer GraphQL for precise querying?

GraphQL isn’t available externally. It’s used exclusively for the POS app and CMS, and isn’t accessible to customers via the API specification.

How can I search by credit card number using the search order SPI?

To search by credit card number using the search order SPI, map the card number to the appropriate fields in the payload. Include the card number under the payment card section. HotWax then reads this information, searches for orders, and returns the results.

Does Point of Sale support query parameters for all SPIs?

No, Point of Sale doesn’t support dynamically populating query parameters. However, you can set up endpoints with static query parameters.

When Point of Sale calls an endpoint, it uses the provided URL exactly as configured. This means that merchants can receive the configured locale (for example, cb-en-us) and store type (for example, stores) as part of the URL. No special handling or logic is applied to these static query parameters — the URL is called as-is.

If merchants are comfortable with the static nature of the query parameters, they can configure them accordingly. This allows them to add conditional processing on their side. Additionally, merchants can use static query parameters to receive authentication codes.

For all SPIs, when error fields are returned with a 200 HTTP response code, should non-nullable fields still be included in the response? For example, in the customer detail API response, the loyaltyProfile field is not nullable and the profile field, while nullable, is required. Please confirm the expected behavior.

Non-nullable fields or any fields not needed in the response should be left out of the response entirely. Instead of inserting a null value for any field not being passed, exclude the field from the response.

In scenarios where a resource is not found and you’d normally return a 404 status, should you return a 200 with error fields populated instead? For instance, if an associate tries to look up a return item based on a registry ID, and the registry ID is invalid, should you return a 200 with an error message instead of a 404?

If returning a 200 status code in a scenario with an empty result string and an error message, Point of Sale displays no results and the error message. If returning a 400 status code, a generic error message is displayed in the app, and the specific error message is captured in the logs.

What is the expected response payload for the order webhook when the status code indicates success? What HTTP status code should I return, and what values should be included in the response fields as indicated in the Swagger documentation?

The current schema doesn’t indicate any required fields. As of now, only a status code response is expected.

If the Address SPI is set up, does the POS always trigger the endpoint and disregard the data in the customer SPI addressList object?

The POS uses the POST address SPI (CREATE_CUSTOMER_ADDRESS) to add an address from the cart’s Select Shipping Address screen. Once the address is added, the POS relies on the addressList provided by CREATE_CUSTOMER_ADDRESS for the checkout process.

What triggers an Order to flow into the Repost Failed Webhook Report?

An order is categorized as a failure and appears in the Repost Failed Webhook report if specific criteria are met during the order export process:

1. HTTP Response Status Code: The order export fails if the HTTP response status code is in the 4xx or 5xx range, indicating a client or server error.
2. HTTP Response Payload: Even with a successful HTTP status code in the 2xx range, the order export is still considered a failure if the response payload includes either or both of these attributes:
   • errorMessage
   • errorCode
   • Example: If the HTTP status code is 200, but the payload contains an error message like the following, the order is marked as a failure:

Is the eReceipt webhook queued in offline mode so that it can be sent once the POS returns to online mode?
The eReceipt webhook is triggered when the app calls the eReceipt API. No emails are sent when an order is synced. However, if automatic receipt emails are configured in the store settings, eReceipts are sent for all orders, even in offline mode. Currently, no customer has automatic receipt emails enabled.

What happens if automatic eReceipts are enabled in offline mode?
If automatic eReceipt emails are configured, the system generates and sends eReceipts during offline sync for every transaction. In this case, remove the email CTA from the order confirmation layout.

Which settings should be enabled to ensure eReceipts are sent automatically in both online and offline modes?
Enable these settings in CMS:

• sendOrderConfirmationEmailAutomatically
• sendRefundEmailAutomatically
• HideReceiptEmailShare

j

Get Started

Develop and Extend

Integration Fundamentals

Point of Sale API, SPI, and Webhook Overview

SPI Error Handling Codes

JSON Sample Payloads & Schemas

Tender Types Attributes in JSON/XML

Set Up Callback URL for Payment Gateway Integrations

Integrate Payment Gateways Using the Payment Gateway SPI

Monitoring Webhook and SPI Integration Health

Configure Monitoring for SPIs and Webhooks in CMS

Data Exports

Clienteling and Associates

Orders and Inventory

Create Distribution Certificate and Resign Development IPA

Test and Validate