Publishes a catalog

POST 
https://euwest.api.elasticpath.com/catalogs/:catalog_id/releases

Publishes a catalog. You must publish a catalog before you can retrieve that catalog in an organization or store. The hierarchies, live products, and prices associated with a published catalog are in read-only mode. If you make a change to these resources, for example, a change to your price book or hierarchies, you need to republish the catalog.

You can get a catalog release to retrieve a published catalog. Currently, published catalogs are limited to the current release and two releases prior to the current release.

You can see the differences between the last 2 consecutive catalog releases. This is useful if want to understand how your products have changed in your catalog, ensuring your site search integration is kept up-to-date.

Once a catalog release has completed publishing, the delta relationship links to the delta document.

The delta links are signed and only valid for 1 hour. Re-reading a catalog release, for example, using Getting a release of a catalog returns a fresh a link.

You can use the is_full_delta attribute returned from the get a release of a catalog endpoint to determine if you need to refresh the data in your company system before injecting fresh data in a delta link. The is_full_delta attribute tells you if this is a full publish of the catalog. Using a search service as an example, if the is_full_delta attribute is true, you should remove all data about that catalog from the search service before injecting fresh data from the delta file. If the is_full_delta attribute is false, then data from the previous catalog overlays the existing data in the delta file. To publish a catalog and inject fresh data in a delta link, set export_full_delta to true.

If a previous catalog publish date is greater than 90 days, then a full catalog publish is automatically performed. If you publish your catalogs infrequently, Commerce may perform a full publish when you are expecting a delta publish.

caution

Generating a full delta is resource intensive and slows down the publishing process and so should only be performed in certain circumstances, for example, when initializing an integration with a service like Algolia.

The is_full_delta attribute is always true the first time a catalog is published. The information is stored in a collection of json documents in a compressed file. You can either manually check the file or, for example, use them to automatically update another company system you may have.

• Delta files are only available for 30 days.
• Delta files are removed when a catalog release is deleted.

Each document has a delta_type with one of the following values, depending on whether a product has been deleted, updated or created in a catalog release.

• delete describes products deleted from this release of a catalog.
• createupdate describes products updated in this release of a catalog.

Multi-Store Management Solutions

In a multi-store management solution.

• You can create organization catalogs. Your organization catalogs are available for your stores to use.
• Your stores can create their own catalogs.
• Your stores can create catalogs that have a combination of organization products and store products.

If you are publishing a catalog in a store that contains resources from an organization, in Commerce Manager, you must enable the Include Organization Resources in Catalog Publishes checkbox.

1. Go to SYSTEM > Store Settings.
2. Click General Settings.
3. Select PXM from the list.
4. Select the Include Organization Resources in Catalog Publishes checkbox.

Request

Path Parameters

catalog_id stringrequired

The catalog ID.

application/json

Body

Options for catalog release publishing

data object

export_full_deltaboolean

Set to true if you want to export all the data from a catalog release in a delta link. The is_full_delta attribute is returned from the get a release of a catalog endpoint. The is_full_delta attribute tells you if the delta file contains the full content of a catalog release. You can use the is_full_delta to determine if you need to refresh the data in your company system before publishing a catalog release with fresh data in a delta link. Using a search service as an example, if the is_full_delta attribute is true, you should remove all data about that catalog from the search service before publishing a catalog release and injecting fresh data from the delta file. If the is_full_delta attribute is false, then data from the previous catalog overlays the existing data in the delta file. The is_full_delta attribute is always true the first time a catalog is published.

include_organization_resourcesbooleannullable

If you are publishing a catalog in a store that contains resources from an organization, you must set this to true and you must enable the Include Organization Resources in Catalog Publishes checkbox in Commerce Manager. See Multi-Store Management Solutions.

Responses

201

Publishes a catalog release with the following attributes.

application/json

Schema

Schema

data object

A catalog release represents a collection of hierarchical product data, price books and catalogs rules.

idstring

A unique identifier for the catalog release.

Example: 8dbb35b2-ef04-477e-974d-e5f3abe6faae

attributes object

namestring

The name of a release.

Example: Clothing

published_atdate-timenullable

The date and time a release was published.

Example: 1970-01-01T00:00:00.000

catalog_idstring

A unique identifier for the catalog.

Example: 0194f54d-f2a1-4e33-9a6e-9ec366152490

descriptionstring

A description of the catalog release.

Default value:

Example: Catalog for Store 123

hierarchies object[]

An array of hierarchy IDs associated with the release.

Array [

idstring

The unique identifier of a hierarchy.

Example: 65477ce0-fcb8-436b-a120-3d57979421dd

labelstring

A label for a hierarchy.

Example: category

namestring

The name of a hierarchy.

Example: Formal dresswear

]

relationships object

Relationships are established between different catalog entities. For example, products, hierarchies, price books, and catalog rules are related to a catalog, as they are associated with it.

delta object

A URL to a delta document that describes the changes between catalog releases.

links object

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

relatedstringrequired

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

products object

A URL to all products included in a catalog release.

links object

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

relatedstringrequired

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

hierarchies object

A URL to all hierarchies included in a catalog release.

links objectrequired

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

relatedstringrequired

A URL to a related object, for example, catalog rules, hierarchies, price books, products and deltas.

typestring

This represents the type of object being returned. Always catalog-release.

meta object

A release's metadata.

created_atdate-time

The date and time a release is created.

Example: 1970-01-01T00:00:00.000

started_atdate-timenullable

The date and time a release is available for use. In other words, the date and time the status of a catalog release changes to PUBLISHED, rather than IN PROGRESS.

Example: 1970-01-01T00:00:00.000

updated_atdate-timenullable

The date and time a release is updated.

Example: 1970-01-01T00:00:00.000

release_statusstring

The status of the current release.

Possible values: [PENDING, IN_PROGRESS, FAILED, PUBLISHED]

languagestring

Your storefront's preferred language code and locale.

Example: en-GB

is_full_publishboolean

Indicates that a full publish was performed (either because this is the first time a catalog has been published or because of a change that occurred, for example, adding/removing a price book or hierarchy). When determining whether delta data needs to be refreshed, ignore this attribute and always use the is_full_delta attribute.

Default value: false

Example: false

is_full_deltaboolean

Indicates whether the release delta file contains the full content of a catalog release. Using a search service as an example, if the is_full_delta attribute is true, you should remove all data about that catalog release from the search service before injecting fresh data from the delta file. If the is_full_delta attribute is false, then data from the previous catalog release overlays the existing data in the delta file. The is_full_delta attribute is always true the first time a catalog is published.

Default value: false

Example: false

total_productsint64nullable

The total number of products displayed in a catalog release.

total_nodesint64nullable

The total number of hierarchy nodes displayed in a catalog release.

percent_completedint32nullable

An integer that represents the progress of a catalog publish. The attribute starts at 0 and reaches 100 when publishing is complete.

ownerstringnullable

The owner of the resource, can be either organization or store.

Possible values: [store, organization]

price_segmentation_enabledboolean

This indicates whether the catalog release will support price segmentation using catalog rules to define which pricebook(s) to use for pricing

links object

Links allow you to move between requests.

selfurinullable

Single entities use a self parameter with a link the specific resource.

firsturinullable

Always the first page.

lasturinullable

This is null if there is only one page.

prevurinullable

This is null if there is only one page.

nexturinullable

This is null if there is only one page.

Example (auto)

{
  "data": {
    "id": "8dbb35b2-ef04-477e-974d-e5f3abe6faae",
    "attributes": {
      "name": "Clothing",
      "published_at": "1970-01-01T00:00:00.000",
      "catalog_id": "0194f54d-f2a1-4e33-9a6e-9ec366152490",
      "description": "Catalog for Store 123",
      "hierarchies": [
        {
          "id": "65477ce0-fcb8-436b-a120-3d57979421dd",
          "label": "category",
          "name": "Formal dresswear"
        }
      ]
    },
    "relationships": {
      "delta": {
        "links": {
          "related": "string"
        }
      },
      "products": {
        "links": {
          "related": "string"
        }
      },
      "hierarchies": {
        "links": {
          "related": "string"
        }
      }
    },
    "type": "string",
    "meta": {
      "created_at": "1970-01-01T00:00:00.000",
      "started_at": "1970-01-01T00:00:00.000",
      "updated_at": "1970-01-01T00:00:00.000",
      "release_status": "PENDING",
      "language": "en-GB",
      "is_full_publish": false,
      "is_full_delta": false,
      "total_products": 0,
      "total_nodes": 0,
      "percent_completed": 0,
      "owner": "store",
      "price_segmentation_enabled": true
    }
  },
  "links": {
    "self": "string",
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  }
}

default

Unexpected error.

application/json

Schema

Schema

errors object[]
Array [
detailstring
Example: not processable
statusstring
Example: 422
titlestring
Example: There was a problem processing your request.
]

Example (auto)

{
  "errors": [
    {
      "detail": "not processable",
      "status": "422",
      "title": "There was a problem processing your request."
    }
  ]
}

Authorization: Authorization

name: Authorizationtype: httpin: headerscheme: bearer

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://euwest.api.elasticpath.com/catalogs/:catalog_id/releases");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <Authorization>");
var content = new StringContent("{\n  \"data\": {\n    \"export_full_delta\": true,\n    \"include_organization_resources\": true\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://euwest.api.elasticpath.com

Auth

Bearer Token

Parameters

catalog_id — pathrequired

Body

{
  "data": {
    "export_full_delta": true,
    "include_organization_resources": true
  }
}

ResponseClear

Click the Send API Request button above and see the response here!