Manage products with the REST API

Access and API keys

L’API client exige Lite ou Premium. Les propriétaires créent et révoquent les clés de l’organisation dans l’application. Chaque clé reste liée à son organisation d’origine et suit l’accès actuel de son créateur : une suspension bloque son utilisation, et le retrait ou le déplacement du créateur supprime ses anciennes clés. Une fermeture ou une limite d’utilisateurs non résolue bloque aussi le travail par API.

Create a key and save its secret

• Open API keys in the organisation you want to connect. Use a separate, clearly named key for each integration so you can identify and revoke it later.
• Choose read-only access for reporting and downloads, or read/write access when the integration needs to change products. Read-only is the default.
• Choose an expiration. The app offers 30 days, 90 days or one year; 90 days is the default.
• Create the key and copy the secret into your server's secret store before dismissing it. Up to 20 active, unexpired keys can exist per organisation.

Copy the secret when it is created: it is shown only once and cannot be recovered. Keep it in your server's secret store, send it in the Authorization header over HTTPS and keep it out of URLs, browser applications and logs. JSON requests use Content-Type: application/json. Replace YOUR_API_KEY below with your secret.

https://api.codepersist.com/api/v1

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Choose the access your integration needs

Read-only keys can list and read products, versions and publication history, preview saved QR artwork and download existing artwork. Read/write keys can also create, update, publish, disable, enable and permanently delete products, and permanently attach an already-connected custom domain. Keys cannot manage billing or other API keys, or connect, verify, list or remove domains.

Each key belongs to one organisation. All reads and changes stay within that organisation, including batch items. A browser cookie does not grant customer API access or change which organisation a key can access.

Plan for key expiration

The expiration starts when the key is created. Replace it before the displayed expiration time to keep the integration running. Expired keys cannot start new requests and return 401. Expiration does not unpublish or disable products that the integration already managed; their printed QR codes keep their existing availability.

Replace or revoke a key

• Create a replacement key in the same organisation with the permissions your integration needs.
• Update your integration's secret store and verify a request with the replacement key.
• Revoke the old key in the app after the integration is using the replacement. Revocation cannot be undone; work already accepted may finish within its original organisation.
• If a secret is exposed, revoke it immediately. Create a replacement and update the integration; the old secret cannot be recovered.

Actions are attributed to the key creator. A change to that creator's organisation invalidates the key. Downgrading to Free blocks API use and key creation, while key listing and revocation remain available in the app. An unexpired, unrevoked key works again after returning to a paid tier.

Create, update and publish

The following examples show HTTP methods, paths and request bodies. Send the authentication header with every request. Replace the uppercase ID placeholders with the UUIDs returned by the API, and use your own GTIN and destination URL.

1. Create an unpublished product

A successful creation returns 201, a Location header and the product document. Save its id and currentVersion.id. Omitting resolverUrl or sending null uses the standard CodePersist resolver. A custom resolver must be an available HTTPS origin owned by your organisation, with an ASCII hostname and no path, query, fragment or credentials; use punycode for internationalized hostnames. The GTIN and original resolver remain fixed. A product created on the CodePersist address can later gain one permanent custom-domain attachment through the customer API, app or Excel import, while keeping its original address. destinationUrl remains required even when you supply resources.

POST /api/v1/products

{
  "name": "SKU-001",
  "gtin": "09506000134352",
  "destinationUrl": "https://brand.example/products/sku-001"
}

2. Read before replacing configuration

Read the product, then send expectedVersionId from currentVersion.id. PUT replaces the editable configuration: name, complete resources and barcode settings. This server-side JavaScript example changes the name while preserving the full resource graph and QR settings. Supply apiKey and productId from your integration. When editing links, preserve every other link, slot and descriptor. Saving creates a new immutable version and does not publish it.

const apiBase = "https://api.codepersist.com/api/v1";
const headers = {
  Authorization: `Bearer ${apiKey}`,
  "Content-Type": "application/json"
};
const response = await fetch(`${apiBase}/products/${productId}`, { headers });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const product = await response.json();

const saved = await fetch(`${apiBase}/products/${productId}`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    expectedVersionId: product.currentVersion.id,
    name: "SKU-001-v2",
    resources: product.currentVersion.resources,
    barcode: product.currentVersion.barcode
  })
});
if (!saved.ok) throw new Error(`HTTP ${saved.status}`);
const updatedProduct = await saved.json();

POST /api/v1/products/PRODUCT_ID/custom-domain

{
  "expectedVersionId": "CURRENT_VERSION_ID",
  "resolverUrl": "https://id.brand.example/"
}

POST /api/v1/products/PRODUCT_ID/publications

{ "expectedVersionId": "VERSION_ID_FROM_ATTACHMENT_RESPONSE" }

3. Publish the saved version

Use the new currentVersion.id after a save. Publishing makes that exact version available to scans at the original address and any attached custom domain. A successful request returns 200 and the product's publication state. A newer save can require a separate publication. A stale expectedVersionId returns 409 so an integration cannot silently publish an unreviewed edit.

POST /api/v1/products/PRODUCT_ID/publications

{ "expectedVersionId": "CURRENT_VERSION_ID" }

4. Generate and download SVG artwork

Production artwork requires the exact current version to be published and enabled. Generation returns 201 with an id, versionId, downloadUrl and sha256. Download the returned URL to retrieve the retained SVG; X-Content-SHA256 identifies the content. Use barcode-preview with the same expectedVersionId to obtain a temporary preview before publishing. The product's digitalLinkUrl is the current artwork URL: it changes after the customer API, app or Excel import permanently attaches a custom domain. resolverUrl keeps the original origin, and earlier retained artwork keeps its original URL. New previews use the attachment immediately; new production artwork requires publication.

POST /api/v1/products/PRODUCT_ID/barcodes

{ "expectedVersionId": "CURRENT_VERSION_ID" }

GET /api/v1/barcodes/BARCODE_ID/svg
Accept: image/svg+xml

Product operations and history

All paths below are relative to /api/v1. Use the OpenAPI reference for complete schemas. Reads and temporary previews need a read-only key; product changes and retained artwork generation need a read/write key.

Products report unpublished, publishing, published, publishFailed, disabling, disabled or disableFailed. After disabling, poll GET /products/{id} until removal completes. Read removalOperationId from that product before enabling, retrying or deleting. Enable requires completed removal; retry requires failed removal; deletion requires the current version and completed removal. Re-enabling leaves the product unpublished. Existing plan limits and lifecycle cooldowns apply.

POST /api/v1/products/PRODUCT_ID/enable

{ "expectedRemovalOperationId": "REMOVAL_OPERATION_ID" }

POST /api/v1/products/PRODUCT_ID/disable/retry

{ "expectedRemovalOperationId": "REMOVAL_OPERATION_ID" }

DELETE /api/v1/products/PRODUCT_ID?expectedVersionId=CURRENT_VERSION_ID&expectedRemovalOperationId=REMOVAL_OPERATION_ID

Product, version and publication lists return items and nextOffset. Use nextOffset for the next request until it is null. offset defaults to 0 and accepts 0–2147483546; limit defaults to 50 and accepts 1–100. Omit optional query parameters to use defaults; empty values are rejected. Pagination is a live view, so concurrent changes may shift results. Product lists accept gtin; compare resolverUrl as well when locating a particular printed identity.

GET /api/v1/products?gtin=09506000134352&offset=0&limit=50

Product and publication times come from the server. They use UTC with exactly six fractional digits and a trailing Z, for example 2026-11-03T14:25:30.123456Z. publishedAtUtc is null before a successful publication and completedAtUtc is null while an attempt is incomplete. A lifecycle error's nextDisableAtUtc uses the same format. V1 requests do not accept client-authored timestamps.

Publish and manage several products

Send up to five distinct products per batch. The same ownership, version and plan checks apply as for individual operations. After selection validation, items run in request order; the batch is not one transaction. Read every item result, even when the HTTP request succeeds. Disable and enable first check ownership of the complete selection: any missing or foreign product rejects the whole request with 404 before changes begin.

POST /api/v1/products/batch/publish

{
  "items": [
    { "productId": "FIRST_PRODUCT_ID", "expectedVersionId": "FIRST_VERSION_ID" },
    { "productId": "SECOND_PRODUCT_ID", "expectedVersionId": "SECOND_VERSION_ID" }
  ]
}

{
  "items": [
    { "productId": "FIRST_PRODUCT_ID", "status": 200, "code": null },
    { "productId": "SECOND_PRODUCT_ID", "status": 200, "code": null }
  ],
  "stopped": false
}

Each returned item has productId, an HTTP status number and an optional safe code. Successful publication and enabling return 200, disabling returns 202 and deletion returns 204. Publication reports foreign products as item-level 404; deletion treats them as absent with 204 and changes nothing. Publication and deletion can return stopped: true with 503 for an uncertain item and 424 for later items not attempted. Disable or enable can instead return an infrastructure error after some items have succeeded. After any uncertain outcome or lost response, read product state before continuing.

Split larger selections into groups of at most five. If publishing times out, stopped can be true: the uncertain item returns 503 and later items return 424 because they were not attempted. Publication recovery may still finish the uncertain item. Read each submitted product and its publication history before retrying, including after a lost response.

Understand errors and retry safely

• 400: check the request fields and correct invalid input.
• 401: check that the secret is correct and the key has not expired or been revoked.
• 403: check the key's permission and the organisation's paid plan.
• 404: check that the resource belongs to the key's organisation. Missing and foreign resources have the same response; deleting either returns 204 without changing another organisation's data.
• 409: read the current product and review version, lifecycle or capacity conflicts before continuing.
• 413: reduce the request body to at most 256 KiB.
• 415: send UTF-8 application/json or application/*+json for an operation that requires a body.
• 429: wait for the Retry-After delay before making another request.
• 5xx: read product state before retrying; work may already have been accepted.
• Error responses use Problem Details with a safe code when available and traceId. Keep the X-Activity-Id response header when contacting support; never include your key.

The API does not support idempotency-key response replay. After an uncertain create, look up the GTIN and resolver before trying again. After any other uncertain write, read the current version and lifecycle state. Refresh after 409 and review the new state instead of blindly retrying. Infrastructure errors can occur after work was accepted; an HTTP failure does not prove that no change occurred.

The management API allows 120 requests per minute per organisation per API instance, shared by all its keys. A batch is bounded to five products. Requests above the rate limit return 429 and Retry-After; respect that delay. Request bodies cannot exceed 256 KiB. These management limits are separate from customer scans.

OpenAPI reference

The versioned customer API starts at /api/v1 on the API host. Its OpenAPI reference describes only the customer endpoints, authentication, request fields and responses. Import it into your API client or use it to generate an integration client. The reference is public; product requests require a key.