THE CANDLE BLISS PARTNER FULFILLMENT API GUIDE (V1.1)

Last updated: January 2, 2026
Applies to: All partners routing end-customer candle orders to Candle Bliss for fulfillment

1. Purpose

This guide defines the required data structure, approved codes, validation rules, and artwork requirements for partners integrating with Candle Bliss for candle production and fulfillment.

This document is the single source of truth.
Any behavior not documented here is not supported.

2. Core Principles

Partner SKUs do not need to match Candle Bliss SKUs
Fulfillment is driven exclusively by required codes
Orders are validated at ingest (reject-fast)
No silent substitutions, no assumptions

3. Required Fields (Per Candle Line Item)

Each candle line item must include the following properties:

Field	Required	Notes
`fulfillment_product`	✅	Must be a valid Candle Bliss code
`fragrance_code`	✅	Must be a valid Candle Bliss code
`print_file_url`	✅	HTTPS · PNG or JPG only · valid 14+ days
`artwork_id`	✅	Unique per line item
`channel_flag_optional`	Optional	Example: `CHANNEL_TIKTOK`

4. Artwork Requirements (Enforced)

Accepted formats: PNG, JPG, JPEG
PDFs and other formats are rejected
File must be:
- Publicly accessible via HTTPS
- Available for at least 14 days
One artwork file per candle line item

5. Example — Single Candle Line Item (Readable Format)

6. Example — Multi-Line-Item Order (2 Candles)

{
  "partner_external_order_id": "PO-1000456",
  "shipping_address": {
    "name": "Jamie Rivera",
    "address1": "123 W Camelback Rd",
    "city": "Phoenix",
    "province": "AZ",
    "zip": "85013",
    "country": "US"
  },
  "tags": ["PARTNER_ACME", "CHANNEL_TIKTOK"],
  "line_items": [
    {
      "variant_id": 111111111,
      "quantity": 1,
      "properties": [
        { "name": "fulfillment_product", "value": "CB_CANDLE_AMBER_9OZ" },
        { "name": "fragrance_code", "value": "CB_FRAG_MORNING_COFFEE" },
        { "name": "print_file_url", "value": "https://partnercdn.com/artwork/labels/order1.jpg" },
        { "name": "artwork_id", "value": "ART-1000456-1" }
      ]
    },
    {
      "variant_id": 222222222,
      "quantity": 2,
      "properties": [
        { "name": "fulfillment_product", "value": "CB_CANDLE_TIN_SILVER_8OZ" },
        { "name": "fragrance_code", "value": "CB_FRAG_WHITE_TEA" },
        { "name": "print_file_url", "value": "https://partnercdn.com/artwork/labels/order2.png" },
        { "name": "artwork_id", "value": "ART-1000456-2" }
      ]
    }
  ]
}

7. Validation Rules (Reject-Fast)

Orders are rejected if any of the following occur:

Missing required fields
Invalid fulfillment_product
Invalid fragrance_code
Unsupported artwork format
Inaccessible artwork URL
Duplicate partner_external_order_id
Inactive or sunset codes

8. Error Response Examples (Exact Payloads)

Invalid Fulfillment Product

Invalid Artwork File Type

9. Catalog (Source of Truth)

All valid codes are published here: https://candlebliss.com/partners/catalog

Partners must build dropdowns and validations from this catalog.