Offer Import

Before Qyren can recommend offers, it needs to know what offers exist. You upload your full catalog once via POST /v1/offers/import, then re-upload whenever the catalog changes — new offer added, price tweaked, contents adjusted.

Endpoint

POST https://api.qyren.ai/v1/offers/import
Authorization: Bearer qyr_live_YOUR_KEY
Content-Type: application/json

Request body

{
  "offers": [ Offer, Offer, ... ]
}

The game_id is resolved from your API key — you don’t pass it in the body. The offers array can hold up to 500 offers per request. If your catalog is larger, page through it in multiple requests.

Per-offer schema

Required fields

Field	Type	Notes
`name`	string	Human-readable name. Shown in dashboards.
`price_usd`	number	Must be greater than 0. For free grants (login bonuses, daily gifts), import them outside this catalog or use a nominal price.
`price_tier`	string	Tier label you use to bucket prices (e.g. `starter`, `mid`, `premium`). Free-form.
`contents_json`	string	A JSON-encoded string describing what the player gets. Format is up to you — Qyren stores it as opaque JSON for display and audit. Example: `"{\"gems\":100,\"gold\":5000}"`.

Optional fields

Field	Type	Notes
`external_id`	string	Your stable ID for this offer. When set, acts as the upsert key — re-importing the same `external_id` updates the offer in place. Without it, every import creates a new row.
`description`	string	Long-form copy. Accepted but not yet persisted.
`is_active`	boolean	Defaults to `true`. Set `false` to import in a paused state.
`sequence_id`	string	Reserved for future sequence binding. Accepted but not yet persisted.
`sequence_step`	integer	Reserved for future sequence binding. Accepted but not yet persisted.

Eligibility rules (level gates, segment targeting, time windows) are not set at import time today. They are managed in the dashboard or via the offer-catalog endpoints once the offer exists.

Upsert behavior

external_id is the upsert key. Re-importing the same external_id updates the offer in place — name, price, contents, active flag. Recommendations served after the import use the new values. If you re-import a partial catalog (say, just the 10 offers you changed today), the offers you didn’t include are left alone, not deleted. This makes incremental updates safe. Offers imported without an external_id cannot be updated through this endpoint — each call creates a new row. Always set external_id if you intend to keep the catalog in sync from your source of truth.

Pausing offers

To remove an offer from rotation, re-import the same external_id with "is_active": false. History is retained and the offer can be re-activated by importing again with "is_active": true. If you need to fully delete an offer (legal/compliance), email [email protected].

Worked example

Here’s a 3-offer import for a fantasy MMO catalog. One starter bundle, one timed weekend deal, one segment-targeted whale offer:

curl -X POST https://api.qyren.ai/v1/offers/import \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offers": [
      {
        "external_id": "starter_bundle_01",
        "name": "Adventurer Starter Bundle",
        "description": "100 gems, 5000 gold, and a hero token to get you started.",
        "price_usd": 4.99,
        "price_tier": "starter",
        "contents_json": "{\"gems\":100,\"gold\":5000,\"hero_token\":1}",
        "is_active": true
      },
      {
        "external_id": "weekend_gem_deal",
        "name": "Weekend Gem Deal",
        "price_usd": 9.99,
        "price_tier": "mid",
        "contents_json": "{\"gems\":300}",
        "is_active": true
      },
      {
        "external_id": "vault_of_legends",
        "name": "Vault of Legends",
        "price_usd": 99.99,
        "price_tier": "premium",
        "contents_json": "{\"gems\":5000,\"gold\":500000,\"legendary_chest\":3}",
        "is_active": true
      }
    ]
  }'

Response

{
  "imported": 3,
  "updated": 0,
  "failed": []
}

imported counts new rows, updated counts upserts against an existing external_id, and failed is an array of {index, reason} for any offers that could not be persisted.

Response codes

Code	Meaning
`200 OK`	Request processed. Inspect the body — individual offers may still appear in `failed`.
`400 Bad Request`	Whole request invalid (malformed JSON, empty `offers`, more than 500 offers).
`401 Unauthorized`	Bad or missing API key.
`404 Not Found`	Game could not be resolved from your key.

Tips

Re-import on every catalog change — even small ones. Stale offers in Qyren mean stale recommendations in your shop.
Always set external_id. It’s the only way to update an offer after the first import. Don’t recycle IDs across different offers — historical performance attaches to the ID.
Encode contents_json as a string. It’s a JSON document inside a JSON string. Quote it correctly in your client code.

Getting Started

Core Concepts

Economy Health

Recommendations

Billing

Integration

API Reference

Glossary

Offer Import

Endpoint

Request body

Per-offer schema

Required fields

Optional fields

Upsert behavior

Pausing offers

Worked example

Response

Response codes

Tips

​Endpoint

​Request body

​Per-offer schema

​Required fields

​Optional fields

​Upsert behavior

​Pausing offers

​Worked example

​Response

​Response codes

​Tips

Endpoint

Request body

Per-offer schema

Required fields

Optional fields

Upsert behavior

Pausing offers

Worked example

Response

Response codes

Tips