Purchases

Some partnership configurations require you to report purchases made on your platform to Lumen. If yours does, use this endpoint.

Report a purchase

POST /partners/v1/purchases

Lumen supports two fulfillment models, configured per partnership and signaled per request via the fulfillment field:

• Lumen-fulfilled (fulfillment: true): Lumen ships the product to the customer. shippingAddress is required.
• Partner-fulfilled (fulfillment: false): you ship the product yourself. Lumen registers the customer for account setup. shippingAddress is not required.

Headers

Header	Type	Required	Description
X-Partner-Api-Key	string	Yes	Your partner API key
Content-Type	string	Yes	application/json

Request body

Field	Type	Required	Description
partnerPurchaseId	string	Yes	Your unique identifier for this purchase. Must be unique per partner.
fulfillment	boolean	Yes	true if Lumen handles fulfillment (ships the product), false if you handle fulfillment yourself
customer	object	Yes	Customer details
customer.email	string	Yes	Customer email address
customer.firstName	string	Yes	Customer first name
customer.lastName	string	Yes	Customer last name
items	array	Yes	List of purchased items
items[].productId	string	Yes	Lumen product ID (provided during onboarding)
items[].quantity	integer	Yes	Quantity ordered (minimum: 1)
shippingAddress	object	Yes*	Shipping destination
shippingAddress.address1	string	Yes*	Street address
shippingAddress.address2	string	No	Apartment, suite, unit, etc.
shippingAddress.city	string	Yes*	City
shippingAddress.state	string	Yes*	State or province
shippingAddress.zip	string	Yes*	Postal / ZIP code
shippingAddress.countryCode	string	Yes*	Two-letter ISO 3166-1 country code (e.g. US)
shippingAddress.phone	string	Yes*	Phone number (digits only, no formatting)
additionalInfo	object	No	Partner-specific metadata
additionalInfo.audienceSegment	string	No	Audience segment (valid values agreed per partner)
properties	object	No	Arbitrary key-value pairs for additional context

* Required when fulfillment is true.

Note

If a purchase with the same partnerPurchaseId has already been reported, the API returns 409 DUPLICATE_PURCHASE. Each partnerPurchaseId must be unique per partner.

Example: Lumen-fulfilled purchase

{
  "partnerPurchaseId": "PARTNER_PUR_123",
  "fulfillment": true,
  "customer": {
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "items": [
    {
      "productId": "LMN_123456",
      "quantity": 1
    }
  ],
  "shippingAddress": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "countryCode": "US",
    "phone": "5551234567"
  },
  "additionalInfo": {
    "audienceSegment": "segment_of_audience"
  },
  "properties": {
    "key1": "value1",
    "key2": "value2"
  }
}

Example: partner-fulfilled purchase

{
  "partnerPurchaseId": "PARTNER_PUR_456",
  "fulfillment": false,
  "customer": {
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "items": [
    {
      "productId": "LMN_123456",
      "quantity": 1
    }
  ],
  "additionalInfo": {
    "audienceSegment": "type_of_audience"
  }
}

cURL

# See "Example: Lumen-fulfilled purchase" above for the full request body.
curl -X POST https://{baseUrl}/partners/v1/purchases \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "pur_a1b2c3d4e5",
    "partnerPurchaseId": "PARTNER_PUR_123",
    "fulfillment": true,
    "createdAt": "2026-03-31T12:00:00Z",
    "customer": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe"
    },
    "items": [
      {
        "productId": "LMN_123456",
        "quantity": 1
      }
    ],
    "shippingAddress": {
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "countryCode": "US",
      "phone": "5551234567"
    },
    "additionalInfo": {
      "audienceSegment": "segment_of_audience"
    },
    "properties": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Errors

HTTP	code	Description
400	INVALID_INPUT	Invalid or missing fields in the request body.
401	UNAUTHORIZED	Missing or invalid API key.
409	DUPLICATE_PURCHASE	A purchase with this partnerPurchaseId already exists. Each partnerPurchaseId must be unique per partner.
429	RATE_LIMIT	Too many requests. The Retry-After header indicates how long to wait.