Campaigns Admin API

The Admin API creates and updates campaigns and packages without going through the dashboard. The main benefit is the full creation flow for a fresh campaign: create the campaign, add its packages, and read back the API key your funnel pages need. That removes the manual setup steps, so an AI agent can drive the entire campaign creation flow for you.

It also pays off once you run more than a handful of campaigns:

• Stand up a campaign per market or per test, each with its own currency and payment methods
• Update every campaign that sells a product after you reprice or discontinue it
• Push a new price to one currency and let the rest recalculate from your default

Permissions

Campaign endpoints are authorized by OAuth scope on the app making the request.

Additional scopes required:

See Admin API permissions for the full scope list and Admin API → Getting Started for creating an OAuth app.

Campaign Provisioning Flow

Standing up a campaign end to end is a 4 step process:

1. Retrieve the payment gateway group using the gatewayGroupsList endpoint to get its id and the payment methods it supports.
2. Create the campaign using the campaignsCreate endpoint.
3. Add a package for each sellable item using the campaignsPackagesCreate endpoint.
4. Read the campaign's api_key from the create response and configure your funnel pages with it.

Create a Campaign

Below is an example API call to create a campaign for a US English funnel that also accepts CAD. name, currency, language, and payment_gateway_group_id are required, everything else is optional.

{
  "name": "Spring Widget Launch US", // internal reference name
  "currency": "USD", // default currency for orders on this campaign
  "language": "en", // preferred customer language
  "payment_gateway_group_id": 4, // from gatewayGroupsList
  "additional_currencies": ["CAD"], // currencies supported beyond the default
  "available_payment_methods": ["card_token", "paypal"], // codes from gatewayGroupsList
  "available_express_payment_methods": ["apple_pay"], // express codes from gatewayGroupsList
  "available_shipping_countries": ["US", "CA"], // ISO 3166-1 alpha-2 codes
  "statement_descriptor": "WIDGETCO" // shown on the customer's card statement
}

The response returns the campaign id you use for every package call, and the api_key your funnel pages authenticate with.

The payment methods you enable have to be ones the gateway group supports. gatewayGroupsList returns each group on the store with its id, available_payment_methods, available_express_payment_methods, and available_currencies.

Add Packages to a Campaign

A package is the campaign's sellable reference to a product or variant, and its id is what your funnel markup passes as data-next-package-id. Only name and product_id are required.

{
  "name": "Widget Single", // package name
  "product_id": 184, // product linked to the package
  "product_variant_ids": [512], // product variants linked to the package
  "price": "49.95" // price per product variant unit
}

Create a Subscription Package

Subscription packages carry a recurring interval and a separate recurring price. interval accepts day or month.

{
  "name": "Widget Monthly Refill",
  "product_id": 184,
  "product_variant_ids": [512],
  "price": "49.95", // charged on the initial order
  "price_recurring": "39.95", // charged on each renewal
  "interval": "month", // day or month
  "interval_count": 1 // renew every 1 month
}

Repricing Across Currencies

campaignsPackagesCreate takes a single price and price_recurring. campaignsPackagesPartialUpdate takes a prices array with one entry per currency, and currencies you leave out are not changed.

{
  "prices": [
    {
      "currency": "USD",
      "price": "44.95",
      "price_recurring": "34.95"
    }
  ],
  "recalculate_prices": true // derive the other currencies from the default currency price
}

With recalculate_prices set to true, every currency you did not list is recalculated from the campaign's default currency price. Left false (the default), only the currencies you passed change.

Find Campaigns to Act On

campaignsList is cursor paginated and filterable. Follow next in the response until it is null.

{}

Audit Packages Against Your Catalogue

campaignsPackagesList filters on name, product_name, and product_sku, so you can find every package on a campaign that sells a discontinued SKU.

{}

Each package returns product_purchase_availability (available or unavailable) and product_inventory_availability (in_stock, low_stock, out_of_stock, or untracked). Check these to catch packages pointing at products customers can no longer buy.

Retire a Campaign or Package

campaignsDestroy deletes a campaign's settings and campaignsPackagesDestroy removes a single package.

Endpoints

Full request and response detail lives in the Admin API reference.

Campaigns

Packages