Documentation

System requirements

• WordPress 6.0 or later
• PHP 7.4 or later
• An active installation of WooCommerce
• A valid licence for Cart URL Generator Pro for WooCommerce
• WooCommerce Composite Products is only required if you wish to use composite products

Installation and activation

1. Download the ZIP file for Cart URL Generator Pro for WooCommerce.
2. In WordPress, go to Plugins > Add a new plugin.
3. Select Upload plugin and select the ZIP file.
4. Install and activate the plugin.
5. Open Cart URL Generator Pro for WooCommerce in the WordPress admin panel.
6. Open the page if necessary Account to activate your licence.

Creating a shopping basket link

1. Select one or more products.
2. For variable products, select the desired product variation.
3. Set the desired quantity for each product.
4. Configure the components of a composite product where necessary.
5. Optionally, add an existing WooCommerce discount code.
6. Choose whether the customer is directed to the shopping basket or straight to the checkout.
7. Generate the shopping basket link.
8. Copy, open or save the link that has been generated.

Supported product types

Simple products

Variable products

WooCommerce Composite Products

Other product extensions

Discount codes

You can link an existing WooCommerce coupon to a shopping basket link. When the customer opens the link, WooCommerce will automatically attempt to apply the coupon to the shopping basket.

The REST API can only use an existing coupon code. It is not possible to create new coupons via the API, nor is it possible to set discount amounts, discount types, usage limits, expiry dates or other coupon conditions.

When the link is opened, WooCommerce carries out the final check based on the actual shopping basket and, where relevant, the customer details.

The standard WooCommerce coupon terms and conditions continue to apply, including:

• start and expiry dates;
• minimum and maximum spending;
• product and category restrictions;
• restrictions and limits on use;
• in combination with other vouchers;
• limits per customer or email address.

Saved shopping basket links

REST API

Endpoint

POST-https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link

Mandatory headers

Content-Type: application/json
X-CUG-API-Key: cug_live_YOUR_API_KEY

Manage API keys

• The full key is displayed only immediately after it has been generated.
• Put the key away in a safe place straight away.
• The plugin then stores the full key in an unreadable format within WordPress.
• A separate key may be revoked at any time.
• Once revoked, applications using that key will immediately cease to work.

Structure of an API request

Available main fields

Fields per item

API examples

A simple product

{
  "items": [
    {
 "product_id": 123,
 "quantity": 1
    }
  ],
  "redirect": "cart"
}

Multiple products

{
  "items": [
    {
 "product_id": 123,
 "quantity": 2
    },
    {
 "product_id": 456,
 "quantity": 1
    }
  ],
  "redirect": "checkout"
}

Product variation

{
  "items": [
    {
 "product_id": 789,
 "quantity": 1
    }
  ],
  "redirect": "checkout"
}

Apply an existing voucher

{
  "items": [
    {
 "product_id": 123,
 "quantity": 1
    }
  ],
  "coupon_code": "WELKOM10",
  "redirect": "checkout"
}

WooCommerce Composite Product

{
  "items": [
    {
 "product_id": 16004,
 "quantity": 1,
 "type": "composite",
 "components": {
 "1780264036": {
 "product_id": 13007,
 "quantity": 1,
 "variation_id": 13043,
          "attributes": {
 "attribute_pa_colour": "dark blonde"
 }
 }
 }
    }
  ],
  "redirect": "checkout"
}

cURL example

curl --request POST \
  --url "https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link" \
  --header "Content-Type: application/json" \
  --header "X-CUG-API-Key: cug_live_YOUR_API_KEY" \
  --data '{
    "items": [
 {
 "product_id": 123,
 "quantity": 1
 }
    ],
    "redirect": "checkout"
  }'

JavaScript example for a secure server environment

const response = await fetch(
  "https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link",
  {
    method: "POST",
    headers: {
 "Content-Type": "application/json",
 "X-CUG-API-Key": process.env.CUG_API_KEY
    },
    body: JSON.stringify({
 items: [
 {
 product_id: 123,
 quantity: 1
 }
 ],
 redirect: "checkout"
    })
  }
);

const data = await response.json();

if (!response.ok) {
  throw new Error(data.message || "The shopping basket link could not be created.");
}

console.log(data.url);

PHP example

$response = wp_remote_post(
    'https://jouwdomein.nl/wp-json/cart-url-generator/v1/create-link',
    [
 'timeout' => 20,
        'headers' => [
 'Content-Type'  => 'application/json',
 'X-CUG-API-Key' => getenv( 'CUG_API_KEY' ),
 ],
 'body' => wp_json_encode(
            [
 'items' => [
 [
 'product_id' => 123,
 'quantity'   => 1,
 ],
 ],
 'redirect' => 'checkout',
 ]
        ),
    ]
);

if ( is_wp_error( $response ) ) {
    throw new RuntimeException( $response->get_error_message() );
}

$status = wp_remote_retrieve_response_code( $response );
$data   = json_decode( wp_remote_retrieve_body( $response ), true );

if ( $status = 300 || empty( $data['url'] ) ) {
    throw new RuntimeException(
 isset( $data['message'] )
            ? $data['message']
 : 'The shopping basket link could not be created.'
    );
}

$cart_url = $data['url'];

API response

Successful application

{
  "success": true,
  "url": "https://jouwdomein.nl/?cug_add=...",
  "meta": {
    "items": 1,
    "redirect": "checkout",
    "coupon_applied": false
  }
}

Error response

{
  "code": "cug_invalid_items",
  "message": "The items array is required and must not be empty.",
  "data": {
    "status": 400
  }
}

Common API statuses

Rate limiting

API request log

Security guidelines

• Please use HTTPS exclusively for API requests and shopping basket links.
• Create a separate API key for each external link.
• Store keys in a secure secret store or server configuration.
• Never include API keys in public front-end code.
• Remove a key immediately if it may have leaked.
• Only grant external systems access to the keys they actually need.
• Please only share links containing a voucher with the intended recipients.
• Do not use the API to simulate orders or payments.
• Validate the API response before using the returned URL.

Cache and security plugins

WooCommerce compatibility

• Simple WooCommerce products are supported.
• Specific WooCommerce product variations are supported.
• Existing WooCommerce coupons can be applied.
• Redirection to the shopping basket and checkout is supported.
• WooCommerce HPOS is supported.
• Traditional WooCommerce order storage remains usable.
• The default configurations of the official WooCommerce Composite Products extension are supported.

Problem-solving

The API does not return a shopping basket link

• Check that the plugin and WooCommerce are active.
• Check that the endpoint is being called on the correct domain.
• Please check whether the application has been submitted with POST will be sent.
• Check whether Content-Type: application/json is present.
• Check the header X-CUG-API-Key.
• Check whether the API key you are using is still active.
• Check whether items is a non-empty array.
• Check the API request log in WordPress.

A product is not being added to the shopping basket

• Check whether the product has been published and is available for purchase.
• Check the stock status.
• For a variable product, use the specific variation ID.
• Check whether the selected variant still exists and is active.
• For a composite product, check all the mandatory components.
• Check whether another plugin is affecting the WooCommerce ‘Add to Cart’ validation.

The voucher will not be applied

• Please check that the voucher code matches exactly.
• Please check that the voucher has been published and has not expired.
• Check the minimum spend, product restrictions and usage limits.
• Check whether the voucher can be combined with other active vouchers.
• Check the WooCommerce notification that appears after opening the link.

The API returns status code 429

The link works for the administrator, but not for visitors

• Try the link in a private window.
• Clear the page and object caches.
• Close cug_add- Disable caching and prefetching for URLs.
• Check firewall and security rules.
• Please check whether the products are available for purchase by the general public.

Data and uninstalling the plugin

Support

• the version of the plugin used;
• the WordPress and WooCommerce version;
• the endpoint used without an API key;
• the HTTP status and error code;
• an anonymised example of the JSON body;
• relevant information from the API request log;
• the steps required to reproduce the problem.