Developer API reference

This reference documents the currently implemented Developer API. Requests must originate from a trusted server. API keys are environment-specific. The API is enabled only where both the Worker and administrative access policy permit it.

Authentication and permissions

Create a seller-owned API key in Dashboard → Settings → Developer API. Use offers:read to list offers and offers:write for image uploads and draft creation. Supply Authorization: Bearer YOUR_API_KEY. Never put secrets in browser JavaScript or logs.

Endpoints

Use GET /developer/v1/catalogue to discover current environment-specific classification IDs and permitted attribute values. This read-only endpoint requires an active offers:read API key. It returns catalogue.categories (top-level categories have parent_id: null; subcategories reference the parent category), catalogue.attributes.definitions (keys, types, options, validation), catalogue.attributes.mappings (attribute-to-category associations), and catalogue.requirements (compliance definitions and mappings). Select an active category with offer_type: product, then its active subcategory; use the subcategory's attribute mappings where applicable. Do not hardcode Production/testing UUIDs for Live. The API still does not edit or publish drafts.

Discover categories and product attributes

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.amajova.com/developer/v1/catalogue"

Use a server-side client to inspect catalogue.categories, catalogue.attributes.definitions, catalogue.attributes.mappings, and catalogue.requirements. This catalogue is shared with the seller offer builder; always validate the chosen attributes and compliance declarations against its current values. An accepted draft is not necessarily eligible to publish.

1. Upload images (optional)

Upload each image separately; only image media is supported. Each upload must be registered to the same seller as the subsequent draft. Maximum file size is 10 MiB. Do not submit arbitrary public URLs as media IDs.

curl -X POST "https://api.amajova.com/developer/v1/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product.jpg"

{"media_upload_id":"UPLOAD_UUID_FROM_MEDIA_RESPONSE","media":{"type":"image","url":"https://..."}}

2. Create a complete physical-product draft

Set Content-Type: application/json and a unique Idempotency-Key (1–128 printable ASCII characters). Reuse the same key and identical JSON bytes only to retry the same operation. A new operation needs a new key. The request body is limited to 65,536 characters; media_upload_ids accepts up to 10 distinct upload UUIDs, in display order. Use an empty array when no images are required.

The example below uses the Production/testing category IDs and four attributes verified for Computer Accessories. Those IDs are environment-specific examples, not a universal catalogue guarantee. Replace the image placeholder with a real upload UUID or remove it.

{
  "template_key": "sell_physical_product",
  "media_upload_ids": [
    "UPLOAD_UUID_FROM_MEDIA_RESPONSE"
  ],
  "offer": {
    "title": "Computer accessories integration example",
    "description": "Computer accessories bundle.",
    "detailed_description": "Demonstration listing. Not for sale.",
    "outcome": "Receive a practical accessories bundle.",
    "price": 49.99,
    "currency": "GBP",
    "delivery_time": "3-5 business days",
    "category_id": "91e20211-6eb9-4420-a121-e66e11be8409",
    "subcategory_id": "33c1c2d5-5839-4dba-9d2f-696f292e717b",
    "stock_quantity": 10,
    "attribute_values": {
      "brand": "Unbranded",
      "condition": "New",
      "compatibility": "Universal computer accessories",
      "colour": "Black"
    },
    "compliance_data": {},
    "shipping_policy": {
      "version": 2,
      "preset_id": null,
      "groups": [
        {
          "countries": [
            {
              "code": "GB",
              "name": "United Kingdom"
            }
          ],
          "cost_type": "free",
          "amount": 0
        }
      ],
      "estimate": "3-5 business days",
      "handling_time": {
        "days": 1,
        "unit": "DAY"
      }
    },
    "return_policy": {
      "returns_accepted": true,
      "days": 14,
      "return_shipping_payer": "buyer"
    },
    "included_items": [
      "Laptop sleeve",
      "Mouse pad",
      "Cable organiser"
    ],
    "excluded_items": [
      "Laptop"
    ],
    "faqs": [
      {
        "question": "Is a laptop included?",
        "answer": "No, accessories only."
      }
    ],
    "trust_terms": [
      "TEST LISTING - NOT FOR SALE."
    ]
  }
}

On initial success the API returns HTTP 201 and {"offer_id":"...","status":"draft","replayed":false}. A successful idempotent replay returns HTTP 200 with replayed:true. This endpoint does not publish the listing.

Product fields and validation

attribute_values is keyed by the selected category’s attribute keys. The server validates and stores normalized objects with labels, values and visibility. For a select attribute, use a permitted option (for example condition: "New"). compliance_data must contain truthful declarations when a category requires them; an empty object may be accepted for a draft but does not imply publication eligibility.

shipping_policy.groups describes destination country codes and delivery costs. return_policy records whether returns are accepted, the number of days and who pays return shipping. Draft acceptance does not guarantee publishing readiness.

3. Create a digital-product draft

Use template_key: "create_and_deliver" (internal type digital_product). The following Production/testing example uses Printables → Planners & Organisers. Category IDs are environment-specific and must be verified before use.

{
  "template_key": "create_and_deliver",
  "media_upload_ids": [],
  "offer": {
    "title": "Digital Productivity Planner - API Test",
    "description": "Digital planner for tasks, schedules and goals.",
    "detailed_description": "Unpublished digital-product integration test.",
    "outcome": "Receive a downloadable productivity planner.",
    "price": 9.99,
    "currency": "GBP",
    "category_id": "19193006-5d3b-486a-922e-e06bc9c69294",
    "subcategory_id": "6c0a4b54-494a-49de-9f4f-e3fff866da23",
    "digital_product_type": "download",
    "digital_access_instructions": "Download instructions will be completed before publication.",
    "digital_license_note": "Personal use only; no resale.",
    "included_items": ["Daily planner", "Weekly planner"],
    "excluded_items": ["Printed copy"],
    "faqs": [{"question":"Is this printed?","answer":"No, this is digital."}],
    "trust_terms": ["Unpublished integration test."]
  }
}

Send this JSON to POST /developer/v1/offers with the same authentication, content type and unique Idempotency-Key headers as the physical-product example. A successful response includes an offer_id and status: "draft". In Production/testing, digital draft creation and database persistence were verified without digital_access_url.

Complete physical-product field checklist

The following fields are accepted in the documented physical-product draft request. Use this checklist to build a listing that a seller can subsequently review. The API creates a draft only; acceptance does not guarantee that every field is complete for publication.

Discover permitted product features

From a trusted server, request GET /developer/v1/catalogue using a key with offers:read. Select the applicable active product category and subcategory. Examine catalogue.attributes.mappings for applicable attributes, then match those entries to catalogue.attributes.definitions to find the attribute keys, input types, permitted options and validation metadata. Submit those keys and permitted values in offer.attribute_values; never assume every product category has the same feature set. Check catalogue.requirements.definitions and catalogue.requirements.mappings for category-specific declarations. For example, the documented Computer Accessories example uses brand, condition, compatibility and colour; other categories may differ.

Multiple-image workflow

Upload each photo separately, save every returned media_upload_id, and provide the IDs in the intended display order when creating the draft. Each image must be no larger than 10 MiB and must belong to the same seller as the API key. A maximum of 10 distinct image IDs can be attached to one draft. Reusing an already-consumed upload ID for a different offer is not supported. The API cannot replace or reorder images on an existing draft; use the seller workflow for later edits.

Important product-page limitations

The API supports the documented fields above. Do not assume it supports arbitrary additional page components, product variants, carts, inventory reservations, draft editing or publishing. Catalogue discovery provides classification and feature rules, not ready-made product marketing copy or automatic answers to FAQs. Developers supply truthful descriptions, inclusions, exclusions, FAQ answers, images and product-specific claims. The seller must review the completed draft before publishing.

Text limits and draft completion

The current seller offer builder limits the short description to 80 characters and the title to 51 characters. Keep API-created drafts within these editor limits so sellers can subsequently save edits without shortening the text. These are seller-editor constraints; the Developer API may accept longer text during draft creation, so an API success response does not mean the draft is ready for editor save or publication. The detailed description is a separate field. Always check category-specific requirements, valid attribute options, genuine digital delivery and compliance before publishing.

Errors and retries

Security and release scope

API keys must remain server-side. Seller identity comes from the key, not a caller-supplied seller ID. Media uploads are seller-bound and single-use when attached. A draft may be incomplete; the seller must review it before publishing. This reference does not grant access to Live or promise publishing endpoints.