Using API

Since Sylius 1.8, we have offered a new API based on ApiPlatform. Below are examples of how to use the API for basic shop operations. Public API documentation is available here.

Register a customer

To register a new customer, send a single POST request:

curl -X 'POST' \
    'https://master-ce.demo.sylius.com/api/v2/shop/customers' \
    -H 'accept: */*' \
    -H 'Content-Type: application/ld+json' \
    -d '{
        "firstName": "shop",
        "lastName": "user",
        "email": "[email protected]",
        "password": "pa$$word",
        "subscribedToNewsletter": true
    }'

If the response status is 204, the customer was registered successfully.

After registering a customer, you can log in to obtain an authentication token, which is required to access more shop endpoints.

curl -X 'POST' \
    'https://master-ce.demo.sylius.com/api/v2/shop/customers/token' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "email": "[email protected]",
        "password": "pa$$word"
    }'

If successful, the response will have a 200 status code and include the token and customer IRI:

{
    "token": "string",
    "customer": "iri"
}

If your shop requires email authentication, no token will be returned.

Use the token to authenticate subsequent API requests:

curl -X 'METHOD' \
    'api-url' \
    -H 'accept: application/ld+json' \
    -H 'Authorization: Bearer token'

Basic Operations: Products, Carts, and Orders

Once the customer is authorized, you can start interacting with products, carts, and orders via the API. Below are the typical operations:

Adding product to cart

Create a Cart:

You can create a cart for a logged-in customer by sending a POST request:

curl -X 'POST' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders' \
  -H 'accept: application/ld+json' \
  -H 'Content-Type: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -d '{
        # "localeCode": "string" (optional)
  }'

You can have your cart in a different locale if needed. If no `localeCode` is provided, the channel's default will be added automatically.

Response status 201 will include cart details and the cart's tokenValue, which is needed for subsequent operations.

Add a Product to the Cart:

First, retrieve a product variant by sending a GET request:

curl -X 'GET' \
  'https://master-ce.demo.sylius.com/api/v2/shop/product-variants?page=1&itemsPerPage=30' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token'

// ...
{
  "@id": "/api/v2/shop/product-variants/Everyday_white_basic_T_Shirt-variant-0",
  "@type": "ProductVariant",
  "id": 123889,
  "code": "Everyday_white_basic_T_Shirt-variant-0",
  "product": "/api/v2/shop/products/Everyday_white_basic_T_Shirt",
  "optionValues": [
    "/api/v2/shop/product-option-values/t_shirt_size_s"
  ],
  "translations": {
    "en_US": {
      "@id": "/api/v2/shop/product-variant-translations/123889",
      "@type": "ProductVariantTranslation",
      "id": 123889,
      "name": "S",
      "locale": "en_US"
    }
  },
  "price": 6420,
  "originalPrice": 6420,
  "inStock": true
}
// ...

Use the @id of the desired variant, and add it to the cart:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/rl1KwtiSLA/items' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "productVariant": "/api/v2/shop/product-variants/Everyday_white_basic_T_Shirt-variant-0",
    "quantity": 1
  }'

The response status 200 confirms the product has been added to the cart.

{
  # Rest of orders body
  "items": [
    {
      "@id": "/api/v2/shop/order-items/59782",
      "@type": "OrderItem",
      "variant": "/api/v2/shop/product-variants/Everyday_white_basic_T_Shirt-variant-0",
      "productName": "Everyday white basic T-Shirt",
      "id": 59782,
      "quantity": 1,
      "unitPrice": 6420,
      "total": 6869,
      "subtotal": 6420
    }
  ],
  # Rest of orders body
}

Changing the Product Quantity in the Cart

To change the quantity of a product already added to the cart, use the following PATCH request:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/OPzFiAWefi/items/59782' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "quantity": 3
  }'

The response status 200 confirms the quantity change.

Completing the Order

Once the cart is filled, follow these steps to complete the order:

1. Add Customer Address

Add the customer's billing and shipping address by sending a PATCH request:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/rl1KwtiSLA/address' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "email": "[email protected]",
    "billingAddress": {
        "city": "California",
        "street": "Coral str",
        "postcode": "90210",
        "countryCode": "US",
        "firstName": "David",
        "lastName": "Copperfield"
      }
  }'

If no shippingAddress is provided, the billingAddress will be used for both.

2. Select Shipping and Payment Methods

First, get the available shipping and payment methods:

curl -X 'GET' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/rl1KwtiSLA' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token'

Use the methods' @id in the next steps.

"payments": [
    {
      "@id": "/api/v2/shop/payments/20446",
      "@type": "Payment",
      "id": 20446,
      "method": "/api/v2/shop/payment-methods/cash_on_delivery"
    }
],
"shipments": [
    {
      "@id": "/api/v2/shop/shipments/17768",
      "@type": "Shipment",
      "id": 17768,
      "method": "/api/v2/shop/shipping-methods/ups"
    }
],

For Shipping:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/rl1KwtiSLA/shipments/17768' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "shippingMethod": "/api/v2/shop/shipping-methods/ups"
  }'

For Payment:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/{cartToken}/payments/{paymentId}' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "paymentMethod": "/api/v2/shop/payment-methods/cash_on_delivery"
  }'

3. Complete the Order

Finally, complete the order by sending the following request:

curl -X 'PATCH' \
  'https://master-ce.demo.sylius.com/api/v2/shop/orders/rl1KwtiSLA/complete' \
  -H 'accept: application/ld+json' \
  -H 'Authorization: Bearer token' \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
    "notes": "your note"
  }'

The response status 200 confirms the order completion, with the checkoutState changed to completed.

{
    # Orders body
    "currencyCode": "USD",
    "localeCode": "en_US",
    "checkoutState": "completed",
    "paymentState": "awaiting_payment",
    "shippingState": "ready",
    # Orders body
}

Final Output

The full checkout process has now been completed using Sylius API. With this API, you can create a fully functional shop frontend based on Sylius' backend logic.