> For the complete documentation index, see [llms.txt](https://help.pixfizz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.pixfizz.com/ecommerce/custom-ecommer-cms.md). # Custom eCommer CMS ## Prerequisites ℹ️ When integrating the Pixfizz design tool with an external site, the Pixfizz site needs to be hosted under the same base domain as the site you are integrating with. The Pixfizz platform uses cookies to store session information. Because modern browsers aggressively block third party cookies, you have to set up your Pixfizz site to be accessible under the same base domain as you main site which you are integrating with Pixfizz. For example, if your main site is available at **[www.mystore.com](http://www.mystore.com)**, you could set up your Pixfizz site to be available at **design.mystore.com**. You can do this by adding your chosen hostname under **Settings → General → Domain Hosting** and setting up a CNAME record that points to `hosting.pixfizz.com`. You must also add the hostname of your main site under **Settings → General → External Hosts** to authorize your site for CORS requests. ## User Handoff The API endpoint `/v1/users/_uid//.json` is used for creating, synchronizing, and logging users from external sites into Pixfizz. The `` parameter is a string identifying your application (the source of external users) and the `` is a unique ID identifying the user in your system. The endpoint whether the user with the given `` from `` already exists in Pixfizz, and creates it with the provided data if not. If the user already exists, it updates it with the provided data if it differs from the user data in Pixfizz. It then logs the user into Pixfizz. To use the endpoint, you send a `POST` request using JavaScript from the client’s browser. The POST body should contain these variables: ``` user[email]=... user[first_name]=... user[last_name]=... hash=... v=4 ``` The `v` parameter identifies the handoff protocol version and should be sent with the value `4`. The `hash` parameter is a security feature that you calculate like this: ```sql md5_hexdigest(md5_hexdigest("||||") + "") ``` You can find the value of your `` in the Pixfizz super admin under **Website → API Settings → Shared Secret**. ❗ You should **NEVER** expose the secret key to the browser. The hash value should be calculated on the server, never on the client. The endpoint is idempotent — calling it multiple times with the same payload does not have any negative side effects. We recommend adding JS code that calls this endpoint in the background after every page load on your site if the user is logged in. At minimum, it should be called: * immediately after user logs into your site * before any interaction with the Pixfizz API ### Example ```jsx const form_data = new FormData(); form_data.append('user[email]', 'user@example.com'); form_data.append('user[first_name]', 'John'); form_data.append('user[last_name]', 'Doe'); form_data.append('hash', '7dae0736c9f358b5fffda200850e60df'); form_data.append('v', '4'); fetch('https://design.mysite.com/v1/users/_uid/mysite/123456.json', { method: 'POST' body: form_data, mode: 'cors', credentials: 'include' }); ``` ### Multilingual Applications If your application supports multiple languages, you can set the language of the user’s session by sending a `POST` request to `/session/set_locale` with the parameter `locale` set to the 2-character language code (`en`, `fr`, `de`, …). ### Logging the User Out To log the user out of Pixfizz, send a `DELETE` request to the `/v1/session.json` endpoint from the user’s browser. It is a good idea to do that immediately after the user logs out of your site. ## Projects ### Creating a Project To create a new project in Pixfizz, you send a `POST` request to the `/v1/books.json` from the user’s browser. The post request body should contain at least these two parameters: * `product_code`: the code of the product in the Pixfizz system * `theme_code`: the code of the design in the Pixfizz system You can also include these optional parameters * `variants[` is the code of the product variant as configured in the Pixfizz admin. The value depends on the variant type: for multi-choice variants, the value should be the code of the chosen option and for text variants it should be the actual text content. Example: `variants[lamination]=glossy`. * `template_options[]`: same as `variants[]` but for setting template options. * `book[name]`: sets the project name. * `book[custom][]`: allows you to set any custom fields that are configured in the Pixfizz admin. These only apply to calendar products. It defines the start date of the calendar. By default the start date is the 1st of January of the current year: * `book[start_year]`: Sets the start year of the generated calendar. Defaults to current year. * `book[start_month]`: Sets the start month of the generated calendar. The value should be a number between 1 (January) and 12 (December). Defaults to 1. * `book[start_day]`: Sets the start day of the generated calendar. The value should be a number between 1 and 31. Defaults to 1. The response returns the project data in JSON format. The data includes an `id` field. You should take the value of the `id` field and redirect the user to the Pixfizz design tool at: `https://design.mysite.com/v1/editor?book=&cart_target=` The `` value should be a URL to which the user will be redirected after clicking the Add to Cart button. The URL can contain a `{{book_id}}` placeholder that will get replaced with the project ID. For example: `https://www.mysite.com/add-pixfizz-product?product_id=1234&project_id={{book_id}}` The handler for this URL should add the project to the cart and store the Pixfizz project ID to the orderline. ### Editing a Project To allow a user to edit a project, you send them to the `/v1/editor?book=` URL that you construct in the same way as in the previous section. If the user is editing a project from their cart, add the `cart=t` parameter to the URL and make sure to adjust the `cart_target` parameter if needed. ### Copying a Project To copy an existing project, send a `POST` request to the `/v1/books//copy.json` endpoint. If you want the copy to be stored into the user’s saved projects, include the `book[saved]` parameter with the value `true` in the POST body. ### Deleting a Project To remove a project from user’s saved projects, send a `PUT` request to `/v1/books/.json` endpoint. The request body should contain the parameter `book[saved]` with the value `false`. ℹ️ The endpoint removes project from user’s saved projects, but it does not actually delete the project from the system. ### Getting User’s Saved Projects To get a list of user’s saved projects, send a `GET` request to `/v1/users//books.json`, where `` is the Pixfizz user ID. To get saved projects of the currently logged in user, you can also send a `GET` request to `/v1/books/_mine.json`, which will redirect you to the `/v1/users//books.json` endpoint with the correct ``. ## Fulfillment Pixfizz supports two types of fulfillment when integrating with external sites: order based and project based. With order based fulfillment you use an API endpoint to re-create the entire order in Pixfizz once the customer successfully checks out on your site. You can assign an external ID to the Pixfizz order to make it easier to cross-reference the orders between the two system. When using order based fulfillment, Pixfizz takes care of generating production PDFs or images, together with any job tickets and sends them to a HTTP endpoint or pushes them to a FTP server. When using project based fulfillment, you use the API to trigger production file generation for individual projects. Once the files for the project are generated, you are responsible for obtaining the download links from the API, downloading the files, and routing them to the appropriate destination. ### Order Fulfillment The endpoint URL is `v1/admin/orders/_external/.json`. It expects a `POST` request with a JSON payload. It requires admin credentials using basic HTTP auth. The endpoint creates a new order in our system, moves it into the "Confirmed" status and initiates fulfillment. Here's an example using cURL: ``` curl \ -u "admin@mystore.com:mypassword" \ -XPOST -H "Content-Type: application/json" \ -d @order.json \ "https://design.mysite.com/v1/admin/orders/_external/mysite.json" ``` Below is an example of `order.json` with some annotations. All fields are required unless otherwise specified. ``` { "order": { "external_reference": "myref-12345",      # unique ID of this order in your system "paid": true, "user_notes": "I need this by Thursday",  # optional; any notes provided by user during checkout "user": { "external_id": "1234321",               # unique ID of the user in your system "email": "my@email.com", "first_name": "John",                   # optional "last_name": "Johnson",                 # optional "telephone": "+12 333 2123"             # optional }, "address": { "first_name": "Johnny", "last_name": "Johnson", "telephone": "123456",                  # optional "company": "Company Ltd",               # optional "street": "Mystreet 42", "street2": "appartment 123",            # optional "city": "Mycity", "postcode": "12345", "region": "Some Region",                # optional "country_code": "FR"                    # ISO 3166-1 alpha-2 country code }, "orderlines": [{ "print_book_id": 48665,                 # Pixfizz project ID; required for design products, should be absent for static products "product_code": "frame-24x24" # Pixfizz product code; required for static products, should be absent for design products "quantity": 2, "unit_price": "12.99",                  # unit price without discounts "discount": "0.49",                    # optional; total discount applied to this orderline "custom": { # optiona; any custom data you want to set on the orderline "external_line_id": "123456" } }], "custom": {                               # optional; any custom data you want to attach to the order "shipping_service": "Fedex" } } } ``` ### Production File Fulfillment To initiate generation of production files for a project, send a `POST` request to the `/v1/books//files.json` endpoint. It requires admin credentials using basic HTTP auth. Sending a POST request initiates generation of production files. The returned JSON data contains an ID of the file and its status. You have to periodically check the status of the files by sending a `GET` request to `/v1/books//files/.json`. The response will show the final URL of the PDF or current status of the job in the queue. The status of the book file will change at different points in the process. * **Queued for processing** *- HTTP: 202:* The file creation job is in the queue, but has not yet begun * **Started** *- HTTP: 202*The file creation job has started, and the file is processing * **Completed** *- HTTP: 200*The file has been created and is ready to download * **Error occurred** - The file creation has failed. Delete the file to try again. The error message field will give more information on what went wrong. * **Deleted** - The file has been deleted. Once you have requested to create a PDF, you cannot do so again without first deleting it. To delete the files you send a `DELETE` request to the `/v1/books//files/.json` endpoint.