Creator attribution via coupon_code in S2S order creation

You can attribute an order to a creator by passing an optional coupon_code field when creating the order via POST /s2s/orders.

How the flow works

1. A player arrives from a creator or referral link on the partner side.
2. The partner stores or resolves the creator code on their side.
3. When the partner creates the order through POST /s2s/orders, they can pass coupon_code to apply that code at order creation time.
4. The Checkout can display the promo code to the player if the integration enables that behavior.
5. If the code is shown in Checkout, the player may remove it or replace it with another promo code before payment.
6. After successful payment, the purchase is fulfilled through the standard post-payment flow, and attribution is based on the coupon code ultimately redeemed at checkout.

Request field

"coupon_code": {
  "type": "string",
  "minLength": 1,
  "title": "Coupon Code",
  "description": "A coupon code to apply to the order on creation. Used for creator attribution when the code belongs to a creator program.",
  "nullable": true
}

Implementation notes

• coupon_code is optional.
• If you choose to show the promo code in Checkout, treat it as user-editable.
• If the player changes or removes the code in Checkout, the final redeemed code is the one that should be used for attribution and analytics.
• Plan an end-to-end integration test after both sides finish implementation, especially if you support referral-link-to-checkout handoff.

Referral link pattern

A common partner pattern is to accept a branded link such as https://yourstore.example/c/{CODE}, resolve the code on the partner side, and then pass it into order creation as coupon_code.

When to show the code in Checkout

Showing the code in Checkout can make the flow more transparent to the player, but it also allows the player to change the code before payment. If you need a strictly background attribution flow, do not rely on Checkout display alone; confirm how your integration handles user edits and what coupon was finally redeemed.