Organization API: Organizations & Members: Campaigns

Part of Organizations & Members.

GET /api/v1/orgs/{org_slug}/campaigns

The organization's saved campaign links, newest first.

Needs the Billing, Admin or Owner role. A campaign is a landing page with the UTM words that tag it and an optional coupon. Every campaign has all its fields, archived (true once it was archived) and url, the full link to copy: the storefront address, base_path, the UTM words in the order utm_source, utm_medium, utm_campaign, utm_term, utm_content, then coupon. The words are percent encoded. An organization with no storefront address gets the path and query alone. count is how many campaigns match before limit and offset apply, and max_campaigns is the most an organization keeps.

POST /api/v1/orgs/{org_slug}/campaigns

Save a campaign link and answer it, with its url.

Needs the Billing, Admin or Owner role. name, utm_source, utm_medium and utm_campaign are required. A bad value answers 422 with detail, the sentence to show, and field, the input it belongs to. A name another campaign already has, in any capitals, answers 409 with field name. An organization keeps at most 500 campaigns, and the 501st answers 409. A coupon_code must be a coupon of this organization. The change is recorded in the audit log as campaign.created.

application/json (required)

POST /api/v1/orgs/{org_slug}/campaigns/preview

Build the link for the fields sent, and list what is wrong with them. Saves nothing.

Needs the Billing, Admin or Owner role. Send the same body as a save; name may be left out. The answer is {url, problems}. problems is a list of {field, detail} with every problem found, and url is null while there is one. The check is the one a save makes, a repeated name and an unknown coupon included.

application/json (required)

GET /api/v1/orgs/{org_slug}/campaigns/results

What every saved campaign brought in over a period, and the campaign words no saved campaign names.

Needs the Billing, Admin or Owner role. The period is from to to in the brand's time zone, the last 30 days when left out, and at most 366 days. A campaign owns the visits, sign-ups and orders whose utm_campaign is its own, ignoring capitals. The figures are the acquisition report's: a visit is a stored session with bots left out, a sign-up is a customer whose last touch named the campaign, an order is a paid order that is not free, and revenue_minor is the invoice total without tax in currency's minor units. Orders and revenue are counted in one currency and never added across currencies: currencies names every currency with an order in the period. conversion_rate_bp is orders over visits in basis points, so 123 is 1.23 percent. visits_complete is false when the period starts more than 180 days ago, because sessions are kept for 180 days. unmatched lists the campaign words of the period that no saved campaign names, the biggest first, at most limit.

PATCH /api/v1/orgs/{org_slug}/campaigns/{campaign_id}

Change the fields of a campaign that were sent, or archive it with archived, and answer it.

Needs the Billing, Admin or Owner role. Only the fields sent are checked and changed, by the rules of a save. A null or empty utm_term, utm_content, coupon_code or notes clears it. Saving what is already there changes nothing and writes no audit entry. A change is recorded as campaign.updated with the names of the fields that changed. A campaign of another organization answers 404.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/campaigns/{campaign_id}

Delete a campaign link. The visits and orders that carried its words stay in the reports.

Needs the Billing, Admin or Owner role. Archive a campaign instead to keep its link and its results in the list. A campaign of another organization answers 404. Recorded as campaign.deleted.

GET /api/v1/orgs/{org_slug}/campaigns/{campaign_id}/results

What one campaign brought in over a period and over the period before it.

Needs the Billing, Admin or Owner role. The figures and their definitions are those of GET results. totals holds visits, signups, orders, new_customers, revenue_minor and conversion_rate_bp, and totals.previous holds the same for the comparison period, or null when compare is none. A campaign of another organization answers 404.