Gifting API

One send is one recipient: for a batch, make one call per recipient with an idempotency key each. There is no sandbox. To test, use a collection with a little test stock and an API key scoped to it; those sends create real packages in your warehouse dashboard, which you can cancel before they are picked.

Until recipient choice is switched on, RECIPIENT_CHOICE answers 403 recipient_choice_unavailable.

• A named sender must be an active member of your company who may send gifts: an owner, a manager, a direct creative, or a member an owner or manager granted Can Send Gifts on the Members page.
• Name nobody and the send is attributed to your company default: the first active owner, then manager.
• sender.externalId (up to 200 characters, for example your CRM user id) is stored and echoed back. It does not name a user.
• Unknown keys in sender are refused, so a misspelt userID cannot fall back to the default silently.

Find sends by CRM record with GET /api/v1/sends?crmProvider=hubspot&crmObjectId=901. Keep recipient details out of metadata: it is erased with the recipient on a privacy request.

• The same key and the same body returns the original send with its current status: HTTP 200 and idempotent: true.
• The same key with a different body is 422 idempotency_key_reused. The body is compared with keys sorted and idempotencyKey removed, so key order does not matter.
• Two identical requests racing each other create one send; both get it back.
• A collection-scoped key reusing another key's idempotencyKey also gets the 422.
• On Gifting & Distribution the daily cap is checked first, so a retry at the cap answers 429.

// First request creates the send
POST /api/v1/sends { "idempotencyKey": "hubspot-901-q4-thanks", "mode": "RECIPIENT_CHOICE", ... }
// 201 { "sendId": "send_...", "status": "awaiting_redemption", "redemptionUrl": "...", ... }

// The same key and the same body returns the existing send and its current status
POST /api/v1/sends { "idempotencyKey": "hubspot-901-q4-thanks", "mode": "RECIPIENT_CHOICE", ... }
// 200 { "sendId": "send_...", "status": "shipped", "createdAt": "...", "idempotent": true, ... }

// The same key with a different body is refused
// 422 { "error": "This idempotencyKey was already used with a different request body.",
//       "code": "idempotency_key_reused" }

• A body that is not valid JSON is 400 invalid_json on every route. It usually means a CRM value (a name with a double quote, an address with a line break) was pasted into a JSON template without escaping. Fix the body; retrying it cannot succeed.
• A 500 with code internal_error is safe to retry. One kind of request is refused before it reaches the API, in another shape: a body larger than 50 MB, or in an encoding or charset the server does not accept, answers 500 { "status": "error", "code": 1000, "message": "Internal server error" }. Fix the request rather than retrying it.

• Creating sends. Gifting & Distribution: 1,000 sends per rolling 24 hours per company, both modes. Business: unlimited. Creates carry X-RateLimit-Limit and X-RateLimit-Remaining; over the cap the answer is 429 with Retry-After, X-RateLimit-Reset and the same numbers in the body.
• Privacy requests. 60 per hour per company, then 429 rate_limited with Retry-After.
• Failures. Every route allows 1,000 failed (4xx or 5xx) responses per 15 minutes per IP address; successful requests do not count. Over it, every request from that address answers 429 rate_limited (with limit, reset and retryAfterSeconds) and Retry-After until the window resets.
• Reads (inventory, list, get), cancel and resend are not metered otherwise.

import crypto from 'crypto';
import express from 'express';

const app = express();

// express.raw keeps the body as the exact bytes Brandmerch signed.
app.post('/webhooks/brandmerch', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-BrandMerch-Signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.BRANDMERCH_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  const eventId = req.get('X-BrandMerch-Event-Id');
  // Already processed eventId? Answer 200 and stop.
  const { event, sendId, data, timestamp } = JSON.parse(req.body.toString('utf8'));
  // Queue the work, then answer within 10 seconds.
  res.sendStatus(200);
});

When a secret is rotated, the old one stops signing at once: update your endpoint in the same step.

Shipping mail is skipped for events more than 72 hours old, for addresses on the Brandmerch suppression list, and for recipients erased on a privacy request.

• Pick & pack: from the start date we announce to your account, each send created on or after it is billed once, when its first package ships: your account's pick & pack rate, a base fee per send plus a fee for each additional item type. Contract rates apply, and a contract that waives the fee books 0. Sends created before the start date are never charged pick & pack.
• Gift add-ons: on those same sends, a gift note or gift box is billed at your account's add-on rate, once per send, together with the pick & pack.
• Shipping: billed at carrier cost on your monthly statement, never per call. If you ship on your own carrier account, your carrier bills you directly.
• GET /api/v1/sends/{sendId} and each send in GET /api/v1/sends show what was booked: fees.pickPackCents is the pick & pack plus gift add-ons (null until the first package ships, and for sends created before your start date; 0 when your contract waives it), and fees.shippingCents is the packages' shipping cost, counted once per shipping label: a package holding several items ships under one label and its cost is counted once, not once per item (null while no package has a cost).

• Covers every send, order, package, gift link response and invitation of your company for that email address (matched case-insensitively), and the stored webhook payloads. Shipping labels and packing slips are deleted from storage.
• Sends that can still be cancelled are cancelled first (send.cancelled with reason privacy_erasure).
• Runs in the background within minutes. Poll GET /api/v1/sends/privacy-delete/{erasureId} until the status is completed, completed_with_exceptions or failed. A failed request did not finish after three attempts: contact support.
• An exception is data that could not be erased on that run; exceptionsByReason counts them per reason. A package that is being picked or packed keeps its address so its label can print (in_fulfillment). Brandmerch then queues a follow-up request for the same address, with a new erasureId, that runs about 24 hours later and again every 24 hours until nothing is left in fulfillment, for up to 30 days after the original request. Filing the same address again returns the waiting follow-up (200, existing: true) and runs it at once.
• Other exceptions, such as a label shared with another recipient's package (shared_label), are not re-run automatically. Contact support if one matters to you.
• Needs an API key without collection scope: an erasure covers your whole company, including sends made with other keys, so a collection-scoped key gets 403 scoped_key_not_allowed on both routes.
• Accepted even if your plan has lapsed. Limited to 60 requests per hour per company.
• Copies already delivered to your systems, such as webhook payloads you stored, are yours to erase.