# Next Commerce: Platform overview > What Next Commerce is, how the two documentation sites divide the material, the Admin API versions, how to test safely, and the legacy identifiers an agent must not "correct". Start here before fetching a domain bundle. This is one of 6 domain bundles derived from the platform capability map at https://developers.nextcommerce.com/capabilities.json (generated 2026-09-03). The other bundles are listed at https://developers.nextcommerce.com/llms.txt. Merchant and operator guides are on https://docs.nextcommerce.com; the changelog is https://docs.nextcommerce.com/changelog. The Admin API contract is the OpenAPI file at https://developers.nextcommerce.com/api/admin/2024-04-01.yaml. ## Capabilities ### Admin API (id: admin-api) The REST Admin API manages store resources: products, orders, customers, subscriptions, fulfillment, payments, campaigns, and more. Access is by OAuth app token against https://{store}.29next.store/api/admin/, with the version selected per request by the X-29next-API-Version header. 2024-04-01 is the stable version; 2023-02-10 is deprecated; unstable carries in-progress changes. Status: available. Audiences: developer. Links verified: 2026-09-03. Caveats: - The developer portal has no changelog of its own; version history is on the merchant changelog. - There is no consolidated migration guide between API versions yet. Merchant and operator guides (docs.nextcommerce.com): - https://docs.nextcommerce.com/docs/build-a-store/technical-settings/configure-webhooks - https://docs.nextcommerce.com/changelog Developer guides (developers.nextcommerce.com): - https://developers.nextcommerce.com/docs/admin-api - https://developers.nextcommerce.com/docs/admin-api/permissions - https://developers.nextcommerce.com/docs/admin-api/guides/exports Admin API operations, version 2024-04-01 (12): - [GET /store/ — Retrieve general business information and store settings.](https://developers.nextcommerce.com/docs/admin-api/reference/store/storeDetail) - [GET /exports/ — Retrieve a list of exports.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsList) - [POST /exports/ — Create a new export.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate) - [GET /exports/types/ — Retrieve all available export types.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsTypesRetrieve) - [GET /exports/{id}/ — Retrieve an export.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsRetrieve) - [GET /exports/{id}/download/ — Retrieve the download URL for a completed export file.](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve) - [GET /metadata/ — Retrieve a list of metadata definitions.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataList) - [POST /metadata/ — Create a new metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataCreate) - [GET /metadata/{id}/ — Retrieve a metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataRetrieve) - [PUT /metadata/{id}/ — Update an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataUpdate) - [PATCH /metadata/{id}/ — Partial update an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataPartialUpdate) - [DELETE /metadata/{id}/ — Delete an existing metadata definition.](https://developers.nextcommerce.com/docs/admin-api/reference/metadata/metadataDestroy) Webhook events (2): - [export.created](https://developers.nextcommerce.com/docs/webhooks/reference/exports/export.created) - [store.updated](https://developers.nextcommerce.com/docs/webhooks/reference/store/store.updated) AI agent skills: - [next-ops-scan](https://github.com/NextCommerceCo/skills/tree/main/next-ops-scan) ### Testing and test orders (id: testing) There is no separate sandbox. Test cards (6011111111111117, and 6011000990139424 for 3DS) create tagged Test Orders on live stores without touching a gateway; the Test Gateway produces realistic test transactions when an integration needs them. Status: available. Audiences: merchant, developer. Links verified: 2026-09-03. Caveats: - Do not tell a prospect there is no test mode; test cards work on live stores. Merchant and operator guides (docs.nextcommerce.com): - https://docs.nextcommerce.com/docs/manage/orders/test-orders - https://docs.nextcommerce.com/docs/features/payments/gateways/test-gateway Developer guides (developers.nextcommerce.com): - https://developers.nextcommerce.com/docs/testing - https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide ### Legacy identifiers (29next) (id: legacy-identifiers) Next Commerce was formerly 29 Next, and the platform still carries that name in its core technical identifiers: store and account hostnames ({store}.29next.store, accounts.29next.com), the X-29next-API-Version and X-29Next-Signature headers, and the API key namespace. These are current, in use on every store, and not scheduled to change. Use them exactly as written. Status: available. Audiences: merchant, developer. Links verified: 2026-09-03. Caveats: - Never rewrite 29next identifiers to nextcommerce; the requests would fail. Merchant and operator guides (docs.nextcommerce.com): - https://docs.nextcommerce.com/docs/start-here/get-started Developer guides (developers.nextcommerce.com): - https://developers.nextcommerce.com/docs/admin-api - https://developers.nextcommerce.com/docs/webhooks ### AI agent skills (id: agent-skills) Pre-built skills that give AI coding agents platform knowledge (theme development, campaign setup, bulk operations, daily ops scans), installable with the skills CLI or loadable as plain markdown. Status: available. Audiences: developer. Links verified: 2026-09-03. Developer guides (developers.nextcommerce.com): - https://developers.nextcommerce.com/docs/skills AI agent skills: - [next-theme-figma](https://github.com/NextCommerceCo/skills/tree/main/next-theme-figma) - [next-theme-dev](https://github.com/NextCommerceCo/skills/tree/main/next-theme-dev) - [next-campaigns-setup](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) - [next-bulk-fulfill](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-fulfill) - [next-bulk-move](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-move) - [next-bulk-subscription](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-subscription) - [next-ops-scan](https://github.com/NextCommerceCo/skills/tree/main/next-ops-scan) ## Pages The full text of every developer page cited above, in the order listed. # Admin API (https://developers.nextcommerce.com/docs/admin-api) ### Getting Started [#getting-started] At the core of Next Commerce, the Admin API lets developers manage store resources, integrate third-party services, and build seamless external order flows. ### Authentication [#authentication] The Admin API uses the OAuth 2 authorization protocol to manage access to your store's resources. OAuth apps and associated access tokens can be tailored with object-level permissions to ensure that each integrated service only has access to the objects it needs. Before using the Admin API, you'll need to create a store and an OAuth app for API access. To create an OAuth app, navigate to **Settings > API Access** and create a new OAuth app with the applicable [permissions](https://developers.nextcommerce.com/docs/admin-api/permissions) to retrieve your **Access Token**. It is recommended to create unique OAuth apps for each external system so you can revoke access as needed. ```bash title="Admin API Path" https://{store}.29next.store/api/admin/ ``` > **Note (Why 29next?):** Next Commerce was formerly 29 Next, and the platform still carries that name in its core technical identifiers: store and account hostnames (`{store}.29next.store`, `accounts.29next.com`), the `X-29next-API-Version` and `X-29Next-Signature` headers, and the API key namespace. These are current, in use on every store, and not scheduled to change. Use them exactly as written. **Use your OAuth app access token in the request headers to access the API.** ```bash title="Example Request" curl -X GET "https://{store}.29next.store/api/admin/" \ -H "Authorization: Bearer " \ -H "X-29next-API-Version: 2024-04-01" ``` > **Warning (Do NOT publish or share Admin API authentication tokens):** Admin API tokens provide full access to your system, including the ability to perform destructive actions like deleting data or users. These tokens should never be shared publicly or exposed in client-side code. > > **Always keep your Admin API tokens private and secure.** ### Versioning [#versioning] API versioning allows Next Commerce to continuously evolve the platform while maintaining predictable behavior for existing APIs with a path for upgrades and deprecations. **Admin API Versions** | Version | Status | Docs | | ------------ | -------------------- | ------------------------------------------------------------------------ | | `2023-02-10` | Deprecated (legacy) | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/2023-02-10/orders/ordersList) | | `2024-04-01` | Stable (recommended) | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/orders/ordersList) | | `unstable` | Unstable | [View Reference](https://developers.nextcommerce.com/docs/admin-api/reference/unstable/orders/ordersList) | **Specify an API Version** To specify a version, pass the `X-29next-API-Version` header with your desired API version. > **Warning:** It is **highly recommended** to specify your version on your API requests to ensure consistency for your integration. ### Rate Limits [#rate-limits] Admin APIs are rate-limited to maintain the stability and equity of our platform for all users. We employ a number of methods to enforce rate limits. | API | Rate Limit Method | Limit | | --------- | ----------------- | ----------------- | | Admin API | Request-based | 4 requests/second | > **Note:** Once you reach API rate limits you'll then receive a 429 Too Many Requests response, and a message that a throttle has been applied. We recommend that API users limit calls appropriately, cache results, and retry requests using industry best practices to avoid rate-limit errors. # Permissions (https://developers.nextcommerce.com/docs/admin-api/permissions) Admin API access is controlled granularly by Scopes that are associated with each OAuth App and associated Access Tokens. | Scope | Detail | | --------------------------- | ------------------------------------------------------------------------- | | `admin:read` | Access to list and view all data | | `admin:write` | Access to create and update all data | | `campaigns:read` | Access to list and view campaigns | | `campaigns:write` | Access to create and update campaigns | | `carts:read` | Access to list and view carts | | `carts:write` | Access to create and update carts | | `catalogue:read` | Access to list and view catalogue objects such as products and categories | | `catalogue:write` | Access to create and update catalogue related objects | | `content:read` | Access to list and view storefront content related objects | | `content:write` | Access to create and update storefront content related objects | | `disputes:read` | Access to list and view disputes | | `disputes:write` | Access to create and update disputes | | `exports:read` | Access to list and view all exports | | `exports:write` | Access to create and update exports | | `fulfillment_service:read` | Access to list assigned fulfillment orders and own locations | | `fulfillment_service:write` | Access to create fulfillment locations and fulfillments | | `fulfillment_orders:read` | Access to list fulfillment order fulfillment requests | | `fulfillment_orders:write` | Access to update fulfillment order fulfillment requests | | `gateways:read` | Access to list and view all gateways and gateway groups | | `gift_cards:read` | Access to list and view all gift cards | | `gift_cards:write` | Access to create and update gift cards | | `locations:read` | Access to list and view all locations | | `locations:write` | Access to create and update locations | | `metadata:read` | Access to list and view all metadata definitions | | `metadata:write` | Access to create and update metadata definitions | | `orders:read` | Access to list and view all orders | | `orders:write` | Access to create and update orders | | `store:read` | Access to list and view store | | `subscriptions:read` | Access to list and view all subscriptions | | `subscriptions:write` | Access to create and update subscriptions | | `themes:read` | Access to list and view all themes | | `themes:write` | Access to create and update themes | | `transactions:read` | Access to list and view all transactions | | `transactions:write` | Access to create and update transactions | | `tickets:read` | Access to list and view all tickets | | `tickets:write` | Access to create and update tickets | | `users:read` | Access to list and view all users | | `users:write` | Access to create and update users | | `webhooks:read` | Access to list and view all webhooks | | `webhooks:write` | Access to create and update webhooks | # API Exports (https://developers.nextcommerce.com/docs/admin-api/guides/exports) The Exports API allows you to generate and download bulk data exports from your store as CSV files. This is useful for reporting, analytics, reconciliation, and data migration workflows. > **Note:** Exports are processed asynchronously. After creating an export, you'll need to poll for completion before downloading the file. ### Export Flow [#export-flow] ```mermaid sequenceDiagram autonumber App->>Store: Subscribe to export.created webhook App->>Store: Create export via API Store->>Store: Export processing Store->>App: export.created webhook event App->>Store: Download export file ``` Creating and downloading an export is a 3-step process: 1. Subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified when exports are ready. 2. Create a new export using the [exportsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate) endpoint with your desired type and date range. 3. When you receive the `export.created` webhook, download the file using the [exportsDownloadRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve) endpoint. ### Available Export Types [#available-export-types] Use the [exportsTypesRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsTypesRetrieve) endpoint to list all available export types, or reference the table below. | Type | Description | | ------------------------- | ----------------------- | | `order_list` | Orders | | `order_line_items` | Order Line Items | | `customer_list` | Customers | | `transaction_list` | Transactions | | `dispute_list` | Disputes | | `subscription_list` | Subscriptions | | `subscription_line_items` | Subscription Line Items | | `open_cart_list` | Open Carts | | `open_cart_line_items` | Open Cart Line Items | | `return_list` | Returns | | `return_line_items` | Return Line Items | | `fulfillment_list` | Fulfillments | | `fulfillment_line_items` | Fulfillment Line Items | ### Create an Export [#create-an-export] To create a new export, send a POST request to the [exportsCreate](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsCreate) endpoint with the export `type` and date range. ```json title="__http:POST:https://{store}.29next.store/api/admin/exports/" { "type": "order_list", // export type "date_from": "2025-01-01T00:00:00Z", // start of date range "date_to": "2025-03-31T23:59:59Z" // end of date range } ``` The response returns the export object with a `pending` status. ```json title="Create Export Response" { "id": 42, "created_at": "2025-04-01T12:00:00Z", "type": "order_list", "status": "pending", "date_from": "2025-01-01T00:00:00Z", "date_to": "2025-03-31T23:59:59Z", "url": "https://{store}.29next.store/api/admin/exports/42/" } ``` ### Poll Export Status [#poll-export-status] After creating an export, poll the [exportsRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsRetrieve) endpoint until the `status` changes from `pending` to `available`. ```json title="__http:GET:https://{store}.29next.store/api/admin/exports/{id}/" { "id": 42, "created_at": "2025-04-01T12:00:00Z", "type": "order_list", "status": "available", // export is ready to download "date_from": "2025-01-01T00:00:00Z", "date_to": "2025-03-31T23:59:59Z", "url": "https://{store}.29next.store/api/admin/exports/42/" } ``` > **Warning:** Avoid polling too frequently. Checking every couple of minutes is sufficient for pending exports. For a more efficient approach, subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified immediately when an export is available for download. ### Download Export File [#download-export-file] Once the export status is `available`, use the [exportsDownloadRetrieve](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsDownloadRetrieve) endpoint to get a download URL for the CSV file. ```json title="__http:GET:https://{store}.29next.store/api/admin/exports/{id}/download/" { "url": "https://example.com/media/{store}/export_csv/{file_name}.csv?signature" // signed download } ``` > **Warning:** Download URLs are temporary signed URLs. Fetch the file promptly after retrieving the URL. If the URL expires, request a new one from the download endpoint. ### Export Webhooks [#export-webhooks] Subscribe to the `export.created` [webhook event](https://developers.nextcommerce.com/docs/webhooks) to be notified immediately when an export is available for download. The webhook payload includes the export object data, allowing you to proceed directly to downloading the file without additional API calls. > **Tip:** Using the `export.created` webhook is the recommended approach for automated export workflows. It eliminates the need for polling and ensures you download the file as soon as it's ready. ### List Exports [#list-exports] Use the [exportsList](https://developers.nextcommerce.com/docs/admin-api/reference/exports/exportsList) endpoint to retrieve previous exports with optional filtering by type and creation date. ```json title="__http:GET:https://{store}.29next.store/api/admin/exports/" { "next": null, "previous": null, "results": [ { "id": 42, "created_at": "2025-04-01T12:00:00Z", "type": "order_list", "status": "available", "date_from": "2025-01-01T00:00:00Z", "date_to": "2025-03-31T23:59:59Z", "url": "https://{store}.29next.store/api/admin/exports/42/" } ] } ``` > **Note:** The list endpoint uses cursor-based pagination. Use the `next` and `previous` URLs in the response to navigate through results. # Testing (https://developers.nextcommerce.com/docs/testing) You can test every order flow on Next Commerce — checkout, upsells, subscriptions, webhooks — **on a live store, without moving real money and without changing any payment settings**. Test cards create tagged Test Orders that never touch a payment gateway, and Test Orders can be deleted when you're done. > **Note (No separate sandbox needed):** There is no separate sandbox environment to provision. Test cards work on live stores and live integrations, so you QA against the exact configuration that will serve real customers. ## Test Cards [#test-cards] Use these card numbers in any checkout — storefront, campaign funnel, or API-driven — to create Test Orders with no attached transactions: | Test Card Number | Expiration | CVV | Use Case | | ---------------- | --------------- | --- | ---------------------------------------------- | | 6011111111111117 | Any Future Date | Any | Test payment success flow without transaction. | | 6011000990139424 | Any Future Date | Any | Test 3DS payment flow without transaction. | Orders created this way are tagged as **Test Orders** in the dashboard, skip the gateway entirely, and are safe to create on stores with live traffic. On the Admin API, you can skip card tokenization during early integration work by using the `test_card` and `test_3ds_card` tokens directly — see the [Testing Guide](https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide) for the token flow. ## Testing Checkout and Campaign Funnels [#testing-checkout-and-campaign-funnels] To QA a campaign funnel (landing → checkout → upsell → receipt) end to end, add your development domain (e.g. `localhost`) as a *development* domain in the Campaigns App so requests are authorized, then pay with a test card at checkout. The [Campaigns getting-started guide](https://developers.nextcommerce.com/docs/campaigns) walks through this, including placing a complete test order. Upsell and post-purchase flows work the same way: the test card carries through the whole funnel, so every accept/decline path can be exercised without a real charge. ## Testing Full Transaction Flows [#testing-full-transaction-flows] Test cards create orders with **no** transactions. If your integration needs realistic transaction objects — captures, declines, refunds — set up the **Test Gateway** (Settings > Payments > Add Gateway), which behaves like a real gateway and produces Test transactions, including a dedicated declined-payment card. > **Warning:** Adding the Test Gateway to your default gateway group can affect live order flows. On stores with live traffic, prefer test cards, or target the Test Gateway by ID through the API. See [Test Gateway setup](https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide). ## Testing Subscriptions and Renewals [#testing-subscriptions-and-renewals] You don't have to wait calendar time to test a renewal: * Create a test subscription through the [Test Gateway](https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide) (Test Gateway subscriptions can create renewal orders; test-card subscriptions cannot). * Trigger a renewal on demand with the [subscriptionsRenewCreate](https://developers.nextcommerce.com/docs/admin-api/reference/subscriptions/subscriptionsRenewCreate) endpoint, or set `next_renewal_date` to a past date and the renewal processes within about 30 minutes. Both are covered in [Subscription Management](https://developers.nextcommerce.com/docs/admin-api/guides/subscription-management). ## Testing Webhooks [#testing-webhooks] Webhook payloads mirror Admin API serializers, so the data your receiver gets matches what a GET on the same resource returns. Set up a test webhook and inspect delivery logs from the dashboard to verify your receiver, and drive events with your test order flows — see the [Webhooks overview](https://developers.nextcommerce.com/docs/webhooks) for payload structure, signature verification, and retry behavior. ## Cleaning Up [#cleaning-up] Test Orders are identifiable and deletable, so QA runs don't pollute reporting. Filter for Test Orders in the dashboard to review or remove them once you're done. # Test Order Flows (https://developers.nextcommerce.com/docs/admin-api/guides/testing-guide) Testing your integration is a critical step when developing on the Next Commerce platform. There are two distinct paths to creating Test Orders, Transactions, and Subscriptions through the Admin API or storefront checkout flow. > **Note (Card Tokenization):** Cards must be tokenized before submitting on the Admin API, see [iframe card tokenization](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard) guide. ### Test Cards [#test-cards] Test cards can be used on live stores and live integrations to create **Test Orders** with the exception they do not touch the gateway and have no attached transactions. | Test Card Number | Expiration | CVV | Use Case | | ---------------- | --------------- | --- | ---------------------------------------------- | | 6011111111111117 | Any Future Date | Any | Test payment success flow without transaction. | | 6011000990139424 | Any Future Date | Any | Test 3DS payment flow without transaction. | > **Tip:** Test cards can be used to test your live integration flows without changing any store payment settings. **Test cards are generally safe to use to test your flows.** ### Test Card Tokens [#test-card-tokens] Test card tokens can be used on the API directly without needing to tokenize the card before submitting the create order request. | Test Card Number | Use Case | | ---------------- | ---------------------------------------------- | | `test_card` | Test payment success flow without transaction. | | `test_3ds_card` | Test 3DS payment flow without transaction. | > **Tip:** Use the test card tokens before you've integrated the [iFrame Card Tokenization](https://developers.nextcommerce.com/docs/admin-api/guides/payment-methods/bankcard) to validate your API requests. ### Test Gateway [#test-gateway] The Test Gateway behaves exactly as a regular gateway, when orders are created using the `test` gateway, they also have associated Test transactions. | Test Card Number | Expiration | CVV | Use Case | | ---------------- | --------------- | --- | ------------------------------------------------------------ | | 4111111111111111 | Any Future Date | Any | Test standard payment flow with successful transaction. | | 5555555555554444 | Any Future Date | Any | Test 3DS payment flow with successful transaction. | | 4012888888881881 | Any Future Date | Any | Test standard payment declined flow with failed transaction. | #### Setup Test Gateway [#setup-test-gateway] To setup the test gateway, go to **Settings > Payments > Add Gateway** to add the Test Gateway to your store. Next, add the Test Gateway to your default gateway group or use the gateway ID directly through the Admin API. > **Warning:** The `test` gateway path requires setting up the gateway and can negatively impact your store's live order flows. **Use with caution if your store has live traffic.** ### Test Subscriptions [#test-subscriptions] Subscriptions can be created with both the [Test Gateway](#test-gateway) and [Test Cards](#test-cards), however there are some small behavior differences at this time. | Test Card Number | Expiration | CVV | Use Case | | ---------------- | --------------- | --- | --------------------------------------------------- | | 4111111111111111 | Any Future Date | Any | Test subscription can create renewal orders. | | 6011111111111117 | Any Future Date | Any | Test subscription **cannot** create renewal orders. | # Webhooks (https://developers.nextcommerce.com/docs/webhooks) Use webhooks to be notified about events that happen in your store. Stores can send webhooks that notify your application anytime an event happens. This is especially useful for building custom reporting solutions that need to receive data on order or customer activity. ### Why Webhooks [#why-webhooks] Webhooks are an efficient way to sync data from a store in near real time, keeping your app up to date without the overhead of traditional polling. See the example below for subscribing to `order.created` events. ```mermaid sequenceDiagram autonumber App->>Store: Subscribes to order.created event Customer->>Store: New order created Store->>App: Sends order.created event payload ``` ### Use Cases [#use-cases] Common use cases include, but are not limited to: * Integrating with external marketing platforms * Collecting data for external reporting applications * Integrating with external fulfillment services * Integrating with dispute management services ### Setting Up Webhooks [#setting-up-webhooks] You can register new webhooks through **Settings > Webhooks** or the Admin API to send event data to your application endpoint. For each webhook, you can subscribe to all events or select specific events to send to your endpoint. See a list of all events and example event data below. > **Warning:** Webhook target endpoints must accept JSON data and respond with a `200` response code. If we do not receive a `200` response, we will retry up to 10 times over a several-day period on an exponential backoff schedule. > > Webhook handlers should also complete within about 20 seconds. Longer-running endpoints can be treated as failed deliveries and retried. > > **Failing webhooks will trigger email notifications to all store admins and will eventually be deactivated.** > > Returning a `410` response code indicates the target resource is no longer available and will automatically disable the webhook. ### Webhook Events [#webhook-events] | Event | Description | Reference | | ---------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `app.uninstalled` | Triggers when an app is uninstalled. *Only available for apps.* | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/apps/app.uninstalled) | | `cart.abandoned` | Triggers when a cart is marked as abandoned. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/carts/cart.abandoned) | | `customer.created` | Triggers when a new customer is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/customers/customer.created) | | `customer.redacted` | Triggers when a customer is redacted. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/customers/customer.redacted) | | `customer.updated` | Triggers when an existing customer is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/customers/customer.updated) | | `dispute.created` | Triggers when a new dispute is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/dispute.created) | | `dispute.updated` | Triggers when a dispute is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/dispute.updated) | | `export.created` | Triggers when an export is available for download. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/exports/export.created) | | `fulfillment.created` | Triggers when a new fulfillment is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/fulfillment/fulfillment.created) | | `fulfillment.updated` | Triggers when a fulfillment is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/fulfillment/fulfillment.updated) | | `gateway.created` | Triggers when a new gateway is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/gateway.created) | | `gateway.updated` | Triggers when a gateway is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/gateway.updated) | | `order.created` | Triggers when an order is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/orders/order.created) | | `order.updated` | Triggers when an existing order is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/orders/order.updated) | | `product.created` | Triggers when a product is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/products/product.created) | | `product.deleted` | Triggers when an existing product is deleted. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/products/product.deleted) | | `product.updated` | Triggers when an existing product is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/products/product.updated) | | `transaction.created` | Triggers when a payment transaction is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/transaction.created) | | `transaction.updated` | Triggers when a payment transaction is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/payments/transaction.updated) | | `subscription.created` | Triggers when a new subscription is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/subscriptions/subscription.created) | | `subscription.updated` | Triggers when an existing subscription is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/subscriptions/subscription.updated) | | `store.updated` | Triggers when store settings are updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/store/store.updated) | | `ticket.created` | Triggers a new support ticket is created. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/support/ticket.created) | | `ticket.updated` | Triggers when an existing support ticket is updated. | [View Example](https://developers.nextcommerce.com/docs/webhooks/reference/support/ticket.updated) | > **Note (Handling subscription charges):** The `subscription` object on a `transaction.created` webhook links the charge to its subscription and identifies the billing cycle. See [Identifying Subscription Charges](https://developers.nextcommerce.com/docs/admin-api/guides/subscription-management#identifying-subscription-charges). > > There is no renewal-specific event. A renewal charge arrives as `transaction.created` with `billing_cycle` of 1 or higher on that `subscription` object; the initial charge has `billing_cycle` 0. > **Note (Disputes include chargebacks):** Chargebacks and pre-chargeback alerts both arrive as `dispute.created` and `dispute.updated`; the dispute's `type` field says which it is. See the [Disputes guide](https://docs.nextcommerce.com/docs/features/payments/disputes-guide). ### Webhook Data Structure [#webhook-data-structure] Webhook payloads follow the same structure as Admin API data serializers, which makes them predictable. In general, the data in a webhook payload matches the data you would get by retrieving the same resource through the API. You can set up test webhooks and view the webhook logs in the dashboard to help build and verify your receiver. ```json title="Webhook Event Payload Structure" { "object": "", "data": "", "event_id": "", "event_type": "", "webhook": "", "api_version": "2023-02-10" } ``` Below is a full example of a webhook payload for a `customer.created` event to demonstrate. ```json title="Example Webhook Event Data" { "api_version": "2023-02-10", "data": { "accepts_marketing": true, "addresses": [], "date_joined": "2021-12-17T14:52:53.715787+07:00", "email": "testing@testing.com", "first_name": "Tester", "id": 32234664, "ip": null, "is_blocked": false, "language": "en", "last_name": "Test", "orders_count": 0, "phone_number": null, "subscriptions_count": 0, "tags": [], "total_spent": null, "user_type": "lead" }, "event_id": "f7eb1338-0934-4cda-8128-d6a77761a368", "event_type": "customer.created", "object": "customer", "webhook": { "events": [ "customer.created" ], "id": 39, "store": "storename", "target": "https://webhook.site/6a880c2a-48db-4e28-a575-294dfee934234" } } ``` ### Webhook API Versions [#webhook-api-versions] Webhook object data structure follows the [Admin API](https://developers.nextcommerce.com/docs/admin-api) and Admin API versioning to ensure predictable data structure for existing webhook receiver endpoints with a path for upgrades. **Handling Webhook API Versions** Your app can add handling logic using the `api_version` key when receiving and processing data to handle multiple webhook data structures while upgrading to a newer webhook api version. ### Verifying Webhook Requests [#verifying-webhook-requests] Webhook endpoints are generally open to the internet and therefore it's a best practice to verify the payload data. Webhook requests include a header `X-29Next-Signature`, the value is a signature of the webhook payload signed using the webhook signing secret. Your application can use the signature to verify the payload authenticity, see an example below. ```python title="Verifying Webhook Payload" webhook_secret = def webhook_payload_validator(request): request_sig = request.headers.get('X-29Next-Signature', None) webhook_data = json.loads(request.body) expected_sig = hmac.new( webhook_secret.encode(), json.dumps(webhook_data).encode(), hashlib.sha256 ).hexdigest() return True if expected_sig == request_sig else False ``` As shown above, we can verify the data by generating the same signature with the webhook secret. > **Tip:** When creating webhooks on the API, you can provide your own signing secret to simplify the signature verification process for webhook payloads. # AI Skills (https://developers.nextcommerce.com/docs/skills) [**Next Commerce AI Skills**](https://github.com/NextCommerceCo/skills) are pre-built skills that give AI coding agents deep knowledge of the Next Commerce platform — APIs, CLI workflows, and architecture patterns — so they can work autonomously on your store. Skills are structured markdown files. Any AI tool that accepts a context file or system prompt can use them — Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, and 50+ other LLM-powered agents. ## Install [#install] The simplest path is the [`skills` CLI](https://github.com/vercel-labs/skills) — it pulls `SKILL.md` files from a GitHub repo and drops them into the right config directory for whichever assistant you use. The target agent is auto-detected by default. ```bash # Install every skill from this repo npx skills add NextCommerceCo/skills # Install one skill npx skills add NextCommerceCo/skills -s next-theme-dev # List skills without installing npx skills add NextCommerceCo/skills --list # Target a specific agent (auto-detected by default) npx skills add NextCommerceCo/skills -a claude-code ``` Once installed, Claude Code auto-detects when a skill is relevant, or you can invoke it directly with `/` (e.g. `/next-theme-dev`). If the skills directory didn't exist before Claude Code started, restart it so it can discover the new directory. ```bash # Update every installed skill npx skills update # Update one skill npx skills update next-theme-dev ``` > **Note:** For agents the `skills` CLI doesn't support, each `SKILL.md` is plain markdown — load it as a system prompt, context file, or chat upload. ### Ask your AI tool to install [#ask-your-ai-tool-to-install] You can also let your AI tool drive the install — it knows where files live for the current OS and assistant: ```text Install the Next Commerce AI skill I need from https://github.com/NextCommerceCo/skills. Use the installation location for my current AI tool and operating system. If my tool supports native skills, install each skill as a directory containing its SKILL.md. If it only supports rules, prompts, or context files, add the relevant SKILL.md there. Prefer HTTPS clone unless my GitHub SSH access is already configured. ``` Tell it which skill you want, or ask it to inspect [`skills.json`](https://github.com/NextCommerceCo/skills/blob/main/skills.json) and choose the relevant one. ## Available skills [#available-skills] | Skill | What it does | When to use it | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | [**next-theme-figma**](https://github.com/NextCommerceCo/skills/tree/main/next-theme-figma) | Prepare Figma storefront designs for Spark theme implementation — validates source structure, classifies sections and assets, records Spark divergences, and generates a low-inference handoff for `next-theme-dev` | You have a Figma storefront design (PDP, homepage, etc.) you want to turn into a Next Commerce theme | | [**next-theme-dev**](https://github.com/NextCommerceCo/skills/tree/main/next-theme-dev) | Build and customize storefront themes — DTL templates, ntk CLI, Tailwind CSS, settings, side cart | You're editing theme files, setting up a new storefront, or debugging template issues | | [**next-campaigns-setup**](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) | End-to-end CPK campaign setup — scaffolds the project, copies a starter template, seeds `campaigns.json`, wires up the API key, store details, and analytics in one pass | Starting a new CPK campaign for a brand | | [**next-bulk-fulfill**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-fulfill) | Update orders to **Fulfilled** with tracking numbers from a CSV | A fulfillment provider shipped orders but tracking didn't sync back — orders stuck in *Processing* | | [**next-bulk-move**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-move) | Move fulfillment orders between warehouse locations in bulk — by order-number file or by Product ID / SKU list | Switching fulfillment providers, or moving every FO containing a given SKU/product to a new location | | [**next-bulk-subscription**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-subscription) | Apply official actions (pause, cancel) or a PATCH (renewal date, interval, gateway, address) to a list of subscription IDs | Merchant wants to bulk-pause, bulk-shift renewals, bulk-cancel, or migrate subscriptions between gateways | | [**next-ops-scan**](https://github.com/NextCommerceCo/skills/tree/main/next-ops-scan) | Read-only daily operations risk scan for a store — surfaces Incomplete orders, Rejected orders, and delivery-tracking failures or stale shipments with manual next steps | You want a routine health check to catch risky orders and reduce disputes | ## Prerequisites [#prerequisites] Each skill lists its own requirements in its `SKILL.md`. Common across all skills: * Access to a Next Commerce store * An API key with the scopes specified by the skill (create at **Dashboard → Settings → API Access**) ## Machine-readable index [#machine-readable-index] For AI agents that need to programmatically discover available skills, [`skills.json`](https://github.com/NextCommerceCo/skills/blob/main/skills.json) is a structured manifest with skill IDs, descriptions, trigger phrases, and prerequisites. Agents can fetch this single file to decide which skill to load.