Gifting

A gift is a normal line that is delivered to a different customer than the one paying. The buyer signs in and pays as usual, while the recipient receives the item in game. Nothing else about the purchase changes.

Naming the recipient

A line can name its recipient in one of two ways.

By platform account. Send gift_to.platform and gift_to.id, for example steam and a SteamID64.

PayNow looks the account up, creates a customer record for it if none exists, and attaches the line to them. This is the form to use when the buyer types in who the gift is for.

By PayNow customer ID. Send gift_to_customer_id when you already have the recipient's customer ID, which you will after the line exists in the cart.

On PUT /v1/store/cart/lines both are query parameters, passed as keys on the SDK's query object:

await storefront.cart.addLine({
  product_id: productId,
  quantity: 1,
  increment: "true",
  "gift_to.platform": "steam",
  "gift_to.id": recipientSteamId,
});

On POST /v1/checkouts they are fields on each line:

await storefront.checkout.createCheckoutSession({
  lines: [
    {
      product_id: productId,
      quantity: 1,
      subscription: false,
      gift_to: { platform: "steam", id: recipientSteamId },
    },
  ],
  return_url,
  cancel_url,
});

What can be gifted

• One-time purchases only. Sending subscription=true together with a gift target returns 400 with the message you can not gift subscriptions. In the UI, disable the gift option when the customer picks subscription billing, or switch the line to one-time when they turn gifting on.
• Products with gifting enabled. Each product carries is_gifting_disabled. Hide the gift option when it is true, because the API rejects the line otherwise.
• Real accounts. An ID that does not resolve to an account returns 400 with player not found. Show that message to the buyer so they can fix the ID. Do not retry.

Collecting the recipient

For Steam stores the recipient is a SteamID64, a 17-digit number starting 7656119. Accept a pasted steamcommunity.com/profiles/<id> URL as well, since that is where players find it.

Vanity URLs (steamcommunity.com/id/<name>) cannot be resolved without a Steam Web API key, so either resolve them on your server with one or tell the customer to use the numeric form. Validate the shape before calling PayNow so the buyer gets an instant error rather than a round trip.

For Minecraft stores a username is enough.

Gift lines in the cart

A gift line is a separate cart line from the same product bought for oneself, so a customer can have both. Each line's gift_to_customer_id tells you which it is.

To change or remove a gift line, send gift_to_customer_id along with the other identifying parameters, otherwise the update targets the non-gift line for that product:

await storefront.cart.addLine({
  product_id: productId,
  quantity: 0,
  increment: "false",
  gift_to_customer_id: recipientCustomerId,
});

After the purchase

The order's lines carry gift: true and gift_to_customer for gifted items, so the buyer's order history can show who each item went to. The recipient sees the item in their own delivery items with gift: true, and it is delivered to them in game exactly as if they had bought it.

Gift cards are a different feature. A prepaid balance the recipient spends themselves. They are sold as products with the grant_giftcard deliverable action and redeemed at checkout, see Gift Cards.