Packs and a common storefront for products

Packs and the web storefront are now part of the public contract. They are available on every plan that includes products, from Esencial. Esencial keeps up to 5 packs per account that are not archived; the other plans have no cap.

• Packs have their own resource: composition, price, availability, images (up to 5, with public and permanent URLs), view=storefront for websites, conditional reads with ETag and a price breakdown by price list, customer (client_id), date and channel.
• Products share the storefront contract: channels.web, slug, summary, seo, sale_price{net, tax, gross}, availability and image alt, width and height. A bulk operation publishes or withdraws up to 50 products.
• Document lines accept {pack_id, quantity, sold_on, unit_price, prices_include_tax, print_mode}. A paid web sale is invoiced with the price charged, to the cent, even if the pack was archived later.
• A pack prints the same way in every document: each product on its own line, labelled with the pack, and the saving under the last one. print_mode only accepts full_breakdown.
• Product lines with unit_price accept prices_include_tax per line.
• Webhooks add pack.created, pack.updated, pack.archived, pack.restored, pack.deleted and product.deleted.

Read Packs and Your store with Factuarea.

Events

New errors: pack_not_found, slug_already_exists, pack_in_use, pack_composition_too_small, invalid_pack_component, duplicate_pack_component, invalid_pack_pricing, pack_price_unreachable, pack_price_allocation_impossible, invalid_pack_status_transition, pack_not_sellable, pack_image_limit_reached, pack_snapshot_invalid, pack_lines_must_be_expanded, pack_line_locked and pack_print_mode_not_allowed.

Contract up to date

This publication also covers the final contract changes for packs, offers and price lists. The affected operations are in the list below.

• Packs. sellable.code is a stable, nullable code (archived, inactive, out_of_window, no_channel, component_unsellable or price_unreachable), and null when the pack can be sold. Changing or deleting the images of a pack that belongs to another company answers 404 pack_not_found.
• Price lists. Updating, deleting or touching the items of a price list from another company answers 404 price_list_not_found. Deleting an item that does not exist answers the new 404 price_list_item_not_found, with param item_id. The domain errors duplicate_price_list_name, invalid_price_list_item, inactive_price_list and price_list_in_use carry their code and their param.
• Idempotency. The write operations of packs, offers and price lists (19 writes) answer 409 idempotency_key_in_use while another request with the same Idempotency-Key is still running. Retry after a few seconds with the same key and body.
• Products. A price[gte], price[lte] or similar filter with a non-numeric value answers 400 parameter_invalid_format, with param.
• Plan cap. On the Esencial plan an account keeps up to 5 packs that are not archived, active or inactive, across its companies. POST /v1/companies/{company}/packs and POST /v1/companies/{company}/packs/{pack}/restore answer 402 plan_limit_exceeded with details.resource packs, current and limit when the account is full, and save nothing. Archive or delete a pack to free a slot, or upgrade the plan. The other plans have no cap.
• Modules. The v1 packs and promotions resources require the products module on every request and answer 403 feature_not_available_in_plan when it is missing. products and price-lists answer as before. A pack line by pack_id in a document requires the packs module.
• Offers. The label accepts 24 characters at most.
• Documents. The line examples include pack_group: null.