Skip to main content
POST /api/v2/storefront/join-links Mints a join link for a storefront your organization owns. Advertisers who sign up through the link become sponsored buyers scoped to that storefront. The approvalPolicy you choose here decides whether those signups are admitted automatically or held for your review.

​
Request

curl -X POST https://api.interchange.io/api/v2/storefront/join-links \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storefrontId": 4012,
    "approvalPolicy": "manual_approve",
    "slug": "northwind-advertisers",
    "maxUses": 250,
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

​
Parameters

FieldTypeRequiredNotes
storefrontIdintegerYesThe storefront_config.id the joining buyer is scoped to. Must belong to your organization.
approvalPolicyenumNoauto_approve, manual_approve, invite_only, or closed. Default manual_approve.
slugstringNoCustom handle (2–64 chars, lowercase letters, numbers, hyphens). Derived from the storefront name when omitted.
expiresAtstringNoISO-8601 expiry. Omit for a link that never expires.
maxUsesintegerNoCap on total successful signups (positive). Omit for unlimited.

​
Response

201 Created with the new JoinLink: 
{
  "id": "5571",
  "slug": "northwind-advertisers",
  "joinPath": "/join/northwind-advertisers",
  "sellerCustomerId": 318,
  "storefrontId": 4012,
  "role": "BUYER",
  "posture": "prepay",
  "approvalPolicy": "manual_approve",
  "active": true,
  "uses": 0,
  "maxUses": 250,
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "revokedAt": null,
  "createdAt": "2026-06-14T18:22:10.441Z",
  "updatedAt": "2026-06-14T18:22:10.441Z"
}
The buyer visits joinPath (/join/{slug}); your UI or agent prepends its own origin to form the full URL.

​
Errors

  • 400 VALIDATION_ERROR — missing storefrontId, or an invalid slug, approvalPolicy, expiresAt, or maxUses.
  • 401 UNAUTHORIZED — missing or invalid API key.
  • 403 CUSTOMER_ROLE_DENIED — the API key is not a seller account; only sellers manage join links.
  • 403 ACCESS_DENIED — the storefrontId belongs to another organization.
  • 404 NOT_FOUND — no storefront with this id exists.
  • 409 CONFLICT — an active link with that slug already exists. Choose a different slug or disable the existing one.
See Errors for the full error contract.

Join-link tasks

All operations

List join links

Every active link

Sponsored buyers

Manage the buyers who joined

Errors

Shared error contract