Use Acenda’s Import and Export API to keep catalog, inventory, pricing, and other marketplace data in sync automatically. This is ideal for running scheduled updates from an ERP, PIM, warehouse system, vendor feed, or custom script without ever logging into the Acenda UI.

This article covers the following automation workflows:

You can automate two main background workflows. The initial API request kicks off the job, and your automation should poll it until it finishes.

Use this flow to update catalog data, inventory, pricing, promotions, tracking, kit components, or channel mappings.

Use this flow to download current Acenda data for reporting, reconciliation, backups, templates, or downstream systems.

Before you begin, ensure you have:

⚠️ Important: Your organization identifier must be sent on every API request using the following header: X-Astur-Organization: your-org-slug. Additionally, the same service account that creates an import preview must be used to manage, finalize, or cancel it.

Acenda uses OAuth2 client credentials authentication. Send a POST request to the token endpoint:

[https://login.acenda.io/auth/realms/acenda/protocol/openid-connect/token](https://login.acenda.io/auth/realms/acenda/protocol/openid-connect/token)

Example Request:

Bash

Include the returned access token in the header of your subsequent API requests:

Authorization: Bearer your-access-token

💡 Tip: Tokens are short-lived. For scheduled or long-running jobs, request a fresh token at the start of each major step or whenever the API returns a 401 status code.

Most API requests should include:

HTTP

Note: For file uploads, do not manually set Content-Type. Allow curl -F or your HTTP client to automatically set the multipart boundary.

Use the following base URL: [https://api.acenda.io/v1](https://api.acenda.io/v1)

There is no tenant-specific subdomain. Your organization is automatically routed via the X-Astur-Organization header.

Imports and exports support: .csv, .csv.gz, .xlsx, and .xlsx.gz.

Note: Tracking currently does not support an export type.

The preview flow helps you validate data before Acenda applies changes.

Bash

⏳ Limits: Preview files expire after 24 hours. Each organization can have a maximum of 50 active, unfinalized previews at one time.

Before finalizing, verify the following fields in the response:

If your header row is not the first row, use the skip_rows parameter to reparse without re-uploading:

Bash

Finalizing creates the actual background processing job.

Bash

💡 Tip: Finalization is safe to retry. If the import job was already successfully triggered, Acenda returns the existing import details instead of creating a duplicate job.

Poll the import record until done returns true.

Bash

If your completed import returns an error_report_path, download the log using:

Bash

Note: If no errors occurred, this endpoint returns a 404 status code.

If you need to reject a file preview and start over, explicitly delete it:

Bash

Returns a 204 No Content response upon success.

Catalog imports use lowercase, case-sensitive column names. The easiest setup template is achieved by exporting your data type first and copying its header row.

Custom fields must use keys prefixed with fields.. Only catalog, channel_item_mapping, and custom_pricing import types support these columns.

Example CSV Format:

Code snippet

💡 Tip: For unit-based custom fields (like weight, dimensions, or volume), separate the metrics into fields.<name>.value and fields.<name>.unit. If you omit the .unit column, Acenda falls back to your catalog's default unit settings.

Image fields ingest publicly accessible asset URLs.

Example CSV Format:

Code snippet

⚠️ Warning: When importing via upsert, image column values replace the product's live image stack completely. If you omit an existing image from the row, it will be removed. To leave a product's current image assets untouched, completely omit all images.* columns from your import file.

Profiles map your system’s unique column naming conventions to Acenda's required field nomenclature. Use this if your raw files originate directly from an ERP, PIM, or warehouse vendor feed.

Bash

Reference the profile ID when executing your finalization step. The preview response will show your file's original columns, but the mappings will execute upon processing:

Bash

Exports run asynchronously. Start the job by calling the endpoint:

Bash

Query the export instance ID until done matches true.

Bash

Extract the exact path value returned by the status response to pull down your final document. Do not manually format this string yourself.

Bash

Filter your data by supplying a URL-encoded MongoDB-style filter to the query parameter.

Example (Filtering inventory for warehouse ID 12):

Bash

Note: If no matching records are found for your filter, the API returns an error instead of an empty document.

💡 Tip: Creating a raw data data export job requires exports:read, not exports:create. The exports:create scope is explicitly reserved for structural Export Profile creations.

This pattern maps reliably to standard scheduling utilities like system cron, Kubernetes CronJobs, or continuous integration pipelines.