diff --git a/content/docs/campaigns/admin-api/index.mdx b/content/docs/campaigns/admin-api/index.mdx index ca7c9aa..3970342 100644 --- a/content/docs/campaigns/admin-api/index.mdx +++ b/content/docs/campaigns/admin-api/index.mdx @@ -60,7 +60,7 @@ Campaign endpoints need API version `2024-04-01` or later. ### Clone a Campaign -- Copies settings, packages and prices, shipping methods, and offers. +- Copies settings, packages and prices, shipping methods, and offers, including their codes. - Package and shipping method IDs stay the same, so existing pages only need the new `api_key`. - The copy is named `-COPY`. Rename it with [campaignsPartialUpdate](/docs/admin-api/reference/campaigns/campaignsPartialUpdate). @@ -74,6 +74,8 @@ A package is the campaign's sellable reference to a product or variant. Its `id` - Only `name` and `product_id` are required. - Create packages before the offers that use them. +- The response is a list with one package per variant, even for a single variant. Read each `id` from the list; the reference shows a single object. +- A variant can be in only one package per campaign. A duplicate returns `400`. Sell it at another price with an offer. - The dashboard creates packages when you pick products in an offer. Call [campaignsPackagesList](/docs/admin-api/reference/campaigns/campaignsPackagesList) first to avoid duplicates. ```json title="Create Package" http-method="POST" http-target="https://{store}.29next.store/api/admin/campaigns/{id}/packages/" @@ -203,6 +205,7 @@ flowchart TD ``` - Create one offer per quantity tier. +- Scope tier offers with `package_ids`. `all_packages` would also discount add-ons. - Only one automatic offer of each benefit type applies. [Concepts → Offers](/docs/campaigns#offers) explains which one wins. - `"available": false` creates the offer switched off. Turn it on with [campaignsOffersPartialUpdate](/docs/admin-api/reference/campaigns/campaignsOffersPartialUpdate). @@ -228,9 +231,16 @@ Automatic offers run only at checkout. Upsell, downsell, and exit-pop discounts ``` -`package_ids` is write-only. The response returns a `packages` array instead. +`package_ids` is write-only. [campaignsOffersRetrieve](/docs/admin-api/reference/campaigns/campaignsOffersRetrieve) returns a `packages` array instead. [campaignsOffersList](/docs/admin-api/reference/campaigns/campaignsOffersList) omits `packages` and `all_packages`, so retrieve an offer to see its scope. +### Update an Offer + +With [campaignsOffersPartialUpdate](/docs/admin-api/reference/campaigns/campaignsOffersPartialUpdate): + +- `condition` replaces the whole condition, so resend `type`, `value` when the type needs one, and `package_ids` or `all_packages: true`. +- `benefit` needs `type` and `value`. An omitted `price_rounding` is kept; `null` clears it. + ### Add Shipping Methods to a Campaign A campaign shipping method sets a campaign price for a shipping method configured on the store. `shipping_method` and `price` are required. @@ -245,7 +255,7 @@ A campaign shipping method sets a campaign price for a shipping method configure } ``` -The campaign's other currencies are converted from this price. To change prices later, [campaignsShippingMethodsPartialUpdate](/docs/admin-api/reference/campaigns/campaignsShippingMethodsPartialUpdate) takes the same `prices` array and `recalculate_prices` flag as [packages](#repricing-across-currencies). +The campaign's other currencies are converted from this price. To change prices later, [campaignsShippingMethodsPartialUpdate](/docs/admin-api/reference/campaigns/campaignsShippingMethodsPartialUpdate) takes the same `prices` array and `recalculate_prices` flag as [packages](#repricing-across-currencies). A bare `price` is ignored. ```json title="Update Shipping Prices" http-method="PATCH" http-target="https://{store}.29next.store/api/admin/campaigns/{id}/shipping-methods/{shippingMethodId}/" { @@ -290,6 +300,10 @@ Check `product_purchase_availability` and `product_inventory_availability` on ea Live funnel pages use the campaign's `api_key` and package IDs. Take them down or repoint them before you delete either. + +Package, offer, and shipping method `id`s start at 1 in each campaign. Always pair one with its campaign `id`. + + Set authorized domains in your store's Campaign Settings, not through this API. See [Concepts → Domains](/docs/campaigns#domains). diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index abe3db4..ab1a113 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -159,6 +159,8 @@ Use the version selector on that site to read the docs for the SDK version your A **campaign** bundles everything needed for a checkout: packages, offers, shipping options, payment methods, and localization. Each campaign has a unique **API key** used by the SDK to authenticate requests. +A campaign serves one language at a time, so another language needs its own campaign. The default currency can't change after create. The API key is safe in browser code; the [authorized domains](#domains) limit where it works. + ### Packages A **package** is the campaign's sellable reference to a product or product variant. In SDK 0.4.x-compatible builds, keep packages focused on identity and base price: @@ -197,7 +199,7 @@ Every offer has a **condition** that decides when it applies and a **benefit** t | `count` | The quantity of a matching package is at or above `value` | Buy 2 or more Widgets | | `count_equal` | The quantity of a matching package is exactly `value` | Exactly 2 Widgets | -A condition targets either every package on the campaign (`all_packages: true`, which also covers packages added later) or a specific list of `package_ids`. In the Campaigns App dashboard, this is the offer's **Products** selection or **All Products**. +A condition targets either every package on the campaign (`all_packages: true`, which also covers packages added later) or a specific list of `package_ids`. In the Campaigns App dashboard, this is the offer's **Products** selection or **All Products**. Use `package_ids` for tier offers, since `all_packages` would also discount full-price add-ons. #### Benefit types @@ -229,6 +231,8 @@ The package's list price stays at $49.95/unit. Each tier is a `count` condition A **shipping method** in a campaign is a virtual link to a shipping method configured on the store, with campaign-specific custom pricing. This lets you charge a different shipping rate (e.g. a flat $4.95 or free shipping) per campaign without changing the underlying store-level shipping method. +For conditional shipping discounts, such as free shipping at 3 or more, use a `shipping_percentage` offer instead of a second shipping method. + ### Domains Domains are configured in your store's **Campaign Settings** and apply across all campaigns. They control which domains are authorized to use your campaign API keys.