How to

Import your product catalog

Import products and variants from your Custom OMS through the API, then choose them for gifting campaigns.

Import your Custom OMS product catalog into Superfiliate so you can choose products and variants for merchant-managed gifting campaigns. Your OMS remains responsible for inventory, order creation, and shipping. The API creates or updates Superfiliate’s copy of each product and its variants.

1. Create API credentials

In Settings → Developers, create server-side credentials with products.write, which also permits product reads. Keep the client ID and secret on your backend. The examples use SF_CLIENT_ID and SF_CLIENT_SECRET environment variables; see API Keys.

2. Map your products and variants

Field	What to send
source, external_id	Required strings. Use a stable catalog source such as custom_oms and your existing OMS product ID. Together they identify the product within your store.
title, url	Required product name and HTTP(S) product page URL.
image_url	Required public HTTP(S) image URL that Superfiliate can fetch. Replace the example URL with a real accessible image.
variants[].external_id, variants[].title	Required for each supplied variant. Use its stable OMS variant ID and a readable name such as Black / Medium.
variants[]: sku, price, options	Optional SKU, decimal price in your store’s configured currency, and name/value options. Send prices as strings, such as 29.99.

Include the variants creators should be able to choose. Keep external IDs unchanged on later imports; they connect selected gift items back to your OMS catalog. Use the returned Superfiliate product id for API lookups, rather than substituting your external ID in the URL.

3. Send one product per request

Create or update a product with one variantbash

curl -X POST "https://api.superfiliate.com/api/v1/products" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "custom_oms",
  "external_id": "everyday-t-shirt",
  "title": "Everyday T-shirt",
  "url": "https://yourstore.com/products/everyday-t-shirt",
  "image_url": "https://yourstore.com/images/everyday-t-shirt.jpg",
  "variants": [
    {
      "external_id": "everyday-t-shirt-black-medium",
      "title": "Black / Medium",
      "sku": "TSHIRT-BLK-M",
      "price": "29.99",
      "options": [
        {
          "name": "Color",
          "value": "Black"
        },
        {
          "name": "Size",
          "value": "Medium"
        }
      ]
    }
  ]
}'

A successful 200 response returns the product object and its variants, including their Superfiliate IDs. Save those IDs alongside your external IDs, then repeat the request for each product in your list. See Upsert product for the full field contract.

Reusing the same source and external_id updates the product. Each included variant is updated by its own external ID within that product.
Each request supports up to 100 variants. For larger products, split variants across requests with the same product fields and IDs. Omitted variants remain unchanged; sending a shorter list does not delete them.
To retire a product or variant, resend its required fields with active: false. Omit optional fields you want to preserve; supplied options replace that variant’s option list.
Save progress per product. Retry network errors, 429s, and server errors with the same IDs and backoff; fix validation errors before retrying. Follow the rate limits.

4. Verify the catalog and choose gift products

Fetch a product using its returned Superfiliate ID. This example assumes 123456; replace it with your actual ID:

Check the imported product and variantsbash

curl "https://api.superfiliate.com/api/v1/products/123456" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

Compare the external IDs, variant options, prices, and image with your source data. List the catalog to reconcile your import, requesting successive pages until an empty array is returned:

List imported productsbash

curl "https://api.superfiliate.com/api/v1/products?page=1&items=25" \
  -H "Authorization: Bearer $SF_CLIENT_ID:$SF_CLIENT_SECRET"

Importing products does not automatically add them to a gifting campaign. Configure the imported variants in your merchant-managed campaign, then have a test creator submit their selections. Confirm the resulting reward’s selected_products contains the expected product and variant external IDs. Continue with Fulfill gifts with your OMS to create the gift order from those selections.