Snipcart Plugin Documentation

# Services

The Snipcart plugin exposes just about everything it can do with Services. Each is accessible everywhere via Snipcart::$plugin->handle, where handle is the "camelCase" name of the class. If you wanted to interact with the Snipcart REST API, for example, you could use $someData = Snipcart::$plugin->api->get('pretend-endpoint') to grab data from a GET request.

# Api (opens new window)

Interacts directly with the Snipcart API via get() or post(). Just specify your desired endpoint and an optional array of parameters.

# getClient()

Returns a configured instance of GuzzleHttp\Client ready to interact with the Snipcart REST API.

# get()

Perform a GET request with the Snipcart API.

Argument Required Description
$endpoint string yes Snipcart API endpoint to be queried
$parameters array array of parameters to be URL formatted
$useCache bool whether or not to cache responses

Returns valid response data as single object or array of objects—otherwise null.

# post()

Perform post request to the Snipcart API.

Argument Required Description
$endpoint string yes Snipcart API endpoint to be queried
$data array array of parameters to be sent

Returns decoded response data.

# put()

Perform put request to the Snipcart API.

Argument Required Description
$endpoint string yes Snipcart API endpoint to be queried
$data array array of parameters to be sent

Returns decoded response data.

# delete()

Perform delete request to the Snipcart API.

Argument Required Description
$endpoint string yes Snipcart API endpoint to be queried
$data array array of parameters to be sent

Returns decoded response data.

# tokenIsValid()

Ask Snipcart whether its provided token is genuine.

Used for webhook requests (except when devMode is true) to verify they were sent by Snipcart.

Tokens are deleted after this call, so it can only be used once to verify and tokens expire in one hour. Expect a 404 if the token is deleted or expired.

Argument Required Description
$token string yes token to be validated, probably from HTTP_X_SNIPCART_REQUESTTOKEN post variable

Returns true if valid, otherwise false.

# invalidateCache()

Invalidate any of the plugin's cached GET requests.

Doesn't return anything.

# Carts (opens new window)

Gets abandoned cart info.

# listAbandonedCarts()

Lists the first page of abandoned cart objects.

WARNING

The plugin's interface matches others with pagination, but Snipcart's API follows a different pagination scheme here and returns hasMoreResults and continuationToken. limit and offset are effectively ignored.

This method will most likely be changed or deprecated in the future.

Returns an object with the following properties.

# getAbandonedCart()

Argument Required Description
$cartId string yes unique ID of an abandoned cart

Returns an AbandonedCart model (opens new window) or null.

# Customers (opens new window)

Lists and searches customer data.

# listCustomers()

List Snipcart customers.

Argument Required Description
$page int page of results (default: 1)
$limit array number of results per page (default: 20)
$params array additional parameters (opens new window) to pass with the REST request; page and limit method parameters will be honored (default: [])

Returns an array of Customer models (opens new window) or null.

# getCustomer()

Get a specific customer by the related Snipcart ID.

Argument Required Description
$customerId string yes Snipcart customer ID

Returns a Customer model (opens new window) or null.

# getCustomerOrders()

Get a customer's complete order history, sorted by descending date.

Argument Required Description
$customerId string yes Snipcart customer ID

Returns an array of Order models (opens new window).

TIP

Note that Snipcart does not populate each Order's items array with this call. If you need individual Order Items, you'll need to make another call to Orders::getOrder().

# Data (opens new window)

Returns store statistics.

# getOrderCount()

Get the number of orders by day between two dates.

Argument Required Description
$from DateTime|int yes DateTime object or Unix timestamp that describes the beginning of the range
$to DateTime|int yes DateTime object or Unix timestamp that describes the end of the range

Returns an object decoded from the following JSON format:

{
  "labels": [
    "Number of orders"
  ],
  "data": [
    {
      "name": "2017-04-04",
      "value": 12
    },
    ...
  ],
  "to": 1493881200,
  "from": 1491289200,
  "currency": null
}

# getPerformance()

Get store performance stats between two dates.

Argument Required Description
$from DateTime|int yes DateTime object or Unix timestamp that describes the beginning of the range
$to DateTime|int yes DateTime object or Unix timestamp that describes the end of the range

Returns an object decoded from the following JSON format:

{
  "ordersSales": 100.00,
  "ordersCount": 10,
  "averageCustomerValue": 10.000000,
  "taxesCollected": 10.00,
  "shippingCollected": 10.00,
  "customers": {
    "newCustomers": 10,
    "returningCustomers": 10
  },
  "averageOrdersValue": 0.000000000000000000000000000,
  "totalRecovered": 0.0
}

# getSales()

Get store saltes totals between two dates.

Argument Required Description
$from DateTime|int yes DateTime object or Unix timestamp that describes the beginning of the range
$to DateTime|int yes DateTime object or Unix timestamp that describes the end of the range

Returns an object decoded from the following JSON format:

{
  "labels": [
    "Total sales"
  ],
  "data": [
    {
      "name": "2017-04-04",
      "value": 120.13
    },
    ...
  ],
  "to": 1493881200,
  "from": 1491289200,
  "currency": null
}

# Discounts (opens new window)

Lists, modifies, and creates store discounts.

# listDiscounts()

Returns an array of Discount (opens new window) models.

# createDiscount()

Creates a new discount.

Argument Required Description
$discount Discount (opens new window) yes discount to be saved

Returns the Snipcart API's decoded response.

# getDiscount()

Gets an existing discount.

Argument Required Description
$discountId string yes unique ID of desired discount

Returns a Discount model (opens new window) or null.

# updateDiscount()

Updates an existing discount.

Argument Required Description
$discount Discount (opens new window) yes discount to be updated

Returns the Snipcart API response object. If successful it will be the updated discount data.

# deleteDiscountById()

Deletes a discount by the supplied ID.

Argument Required Description
$discountId yes unique ID of desired discount

Returns the Snipcart API's decoded response.

# Fields (opens new window)

Gets and saves Product Details field data. (Used by included Field Type.)

# saveProductDetailsField()

Saves data (in a record) for a Product Details field.

Argument Required Description
$field ProductDetails (opens new window) yes field to be saved
$element ElementInterface yes relevant Element

Returns true if successful or null if the field's data is empty.

# getProductDetailsField()

Fetches the data for a Product Details field.

Argument Required Description
$field ProductDetails (opens new window) yes related Field
$element ElementInterface relevant Element
$value optional value that should be used to populate the model, otherwise it will be populated with record data or field defaults accordingly

Returns ProductDetails model (opens new window) or null.

# Notifications (opens new window)

Sends notifications as things happen. Currently just email.

WARNING

This service is likely to change as parts are abstracted to a future Notification model for validation and broader notification options (Slack, etc.).

# setNotificationVars()

Sets template variables for the notification. Should be called before sendEmail().

Argument Required Description
$data array|object yes Twig variables meant for the notification template

Doesn't return anything.

# getNotificationVars()

Gets template variables for the notification.

Returns an array, object, or null.

# setErrors()

Sets notification errors.

Argument Required Description
$data array yes array of error strings compatible with parent's setErrors()

Doesn't return anything.

# setEmailTemplate()

Sets notification email template.

Argument Required Description
$htmlTemplate string yes Twig template path to be used for the HTML email notification
$textTemplate string Twig template path to be used for an alternate, plain text email notification
$frontend boolean whether the supplied path is on the front (site) end or the back (plugin) end, which matters for setting the template mode (default: false)

Doesn't return anything.

# sendEmail()

Sends an email notification.

Argument Required Description
$to array yes array of valid email addresses
$subject string yes message subject

Returns true if successful, otherwise false. If it didn't go well, use getErrors() to find out why.

# Orders (opens new window)

Interacts with Orders.

# getOrder()

Gets a Snipcart order by ID.

Argument Required Description
$orderId string yes unique ID of the order

Returns Order model (opens new window) or null.

# getOrders()

Gets Snipcart orders, optionally by parameters supported by Snipcart's REST API (opens new window).

Argument Required Description
$params array parameters used for fetching results

Returns an array of Order models (opens new window).

# getAllOrders()

Gets Snipcart orders, optionally by parameters supported by Snipcart's REST API (opens new window), quietly aggreggating results across pagination from the REST API.

WARNING

Careful using this as long result sets could require a long wait!

Argument Required Description
$params array parameters used for fetching results

Returns an array of Order models (opens new window).

# getOrderNotifications()

Gets the notifications Snipcart has sent regarding a specific order.

Argument Required Description
$orderId string yes unique ID of the order

Returns an array of Notification models (opens new window).

# getOrderRefunds()

Gets a Snipcart order's refunds.

Argument Required Description
$orderId string yes unique ID of the order

Returns an array of Refund models (opens new window).

# listOrders()

Gets Snipcart orders specifically including pagination info.

Argument Required Description
$page int desired page of results (default: 1)
$limit int number of results per page (default: 25)
$params array parameters used for fetching results

Returns an object with the following keys:

  • items: array of Order models (opens new window) up to the pagination limit
  • totalItems: int representing the result set's total number of orders
  • offset: int pagination offset
  • limit: pagination limit

# updateProductsFromOrder()

Get Craft Elements that relate to order items, updating quantities if that field setting is enabled and the item has a non-zero quantity value.

Argument Required Description
$order Order (opens new window) yes order whose items should be checked

Returns true if successful, or an array of errors if a resulting notification failed.

# getOrderPackaging()

Triggers EVENT_BEFORE_REQUEST_SHIPPING_RATES to allow another plugin or module to provide packaging details for an order before shipping rates are requested.

Argument Required Description
$order Order (opens new window) yes order for which shipping rates will be requested

Returns the Package (opens new window) model, populated by an event hook or instantiated but literally and symbolically empty.

# sendOrderEmailNotification()

Have Craft email an order notification.

Argument Required Description
$order Order (opens new window) yes the relevant Snipcart order
$extra array extra variables meant for the Twig notification template
$type string notifyAdmin or notifyCustomer (default: notifyAdmin)

Returns true if successful, otherwise an array of error strings.

# refundOrder()

Applies a refund to an order.

Argument Required Description
$order Order (opens new window) yes the relevant Snipcart order
$amount float yes the amount to be refunded
$comment string refund comment
$notifyCustomer bool whether to send a Snipcart notification to the customer (default: false)

Returns the decoded response from the Snipcart REST API.

# Products (opens new window)

Handles local product data related to Snipcart Orders.

# reduceInventory()

Adjusts the supplied Entry's product inventory by the quantity value if...

  • it uses the Product Details field and
  • its inventory value exists and is greater than zero

EVENT_PRODUCT_INVENTORY_CHANGE will also be fired before the adjustment so an Event hook can modifies the quantity property prior to the adjustment.

Argument Required Description
$orderItem Item yes Snipcart Item that was part of a completed order

Doesn't return anything.

# Shipments (opens new window)

Facilitates optional interaction with ShipStation.

# getShipStation()

Returns an instance of the ShipStation provider (opens new window).

# collectRatesForOrder()

Collects shipping rate options for a Snipcart order. Triggers EVENT_BEFORE_RETURN_SHIPPING_RATES so that existing rate, order, or packaging details can be modified by an Event hook before querying ShipStation's REST API for rates.

Argument Required Description
$order Order (opens new window) yes order for which shipping rate options are needed

Returns an array with two keys:

# handleCompletedOrder()

Handles an order that's been completed, normally sent after receiving a webhook post from Snipcart.

Argument Required Description
$order Order (opens new window) yes order that's just been completed

Returns an array with the following keys:

# getQuoteLogForOrder()

Get the last shipping rate quote that was returned for the given order.

Argument Required Description
$order Order (opens new window) yes order whose rate quotes we're looking for

Returns most recent ShippingQuoteLog that matches the Snipcart order ID, if found.

# Subscriptions (opens new window)

Interacts with Snipcart subscriptions.

# listSubscriptions()

Returns Snipcart subscriptions.

Argument Required Description
$page int desired page of results (default: 1)
$limit int number of results per page (default: 25)
$params array parameters used for fetching results

Returns an object with the following keys:

  • items: array of Subscription models (opens new window) up to the pagination limit
  • totalItems: int representing the result set's total number of subscriptions
  • offset: int pagination offset
  • limit: pagination limit

# getSubscription()

Gets a Snipcart subscription.

Argument Required Description
$subscriptionId string yes Snipcart subscription ID

Returns a Subscription model (opens new window) or null.

# cancel()

Cancels a subscription.

Argument Required Description
$subscriptionId string yes Snipcart subscription ID

Returns decoded response data from the Snipcart REST API.

# pause()

Pauses a subscription.

Argument Required Description
$subscriptionId string yes Snipcart subscription ID

Returns decoded response data from the Snipcart REST API.

# resume()

Resumes a subscription.

Argument Required Description
$subscriptionId string yes Snipcart subscription ID

Returns decoded response data from the Snipcart REST API.

# Webhooks (opens new window)

Handles posts sent to the Webhooks controller (opens new window) by prepping models and dispatching Events.

# setData()

Sets the payload data and derived mode to be utilized within the service and quietly logs the request before processing if logging is enabled.

Argument Required Description
$payload mixed yes decoded request body that Snipcart posted to the webhook

Doesn't return anything.

# getData()

Returns payload data in whatever format it was received. Or null.

# setMode()

Explicitly sets the webhook mode, which should be either Live or Test. Returns that mode.

# getMode()

Returns the current webhook mode, which should be either Live or Test.

# handleOrderCompleted()

Handles a completed order. Returns an array with the following keys:

  • success: boolean, true if everything went as expected with no errors
  • errors: an array of strings that represent errors encountered handling the order

# handleShippingRatesFetch()

Handles a shipping rate request by calling shipments->collectRatesForOrder(), logging any custom rates, and returning that array of ShippingRate models (opens new window).

# handleOrderStatusChange()

Handles an order status change. Returns [ 'success' => true ].

# handleOrderPaymentStatusChange()

Handles an order payment status change. Returns [ 'success' => true ].

# handleOrderTrackingNumberChange()

Handles an order tracking number change. Returns [ 'success' => true ].

# handleSubscriptionCreated()

Handles a created subscription. Returns [ 'success' => true ].

# handleSubscriptionCancelled()

Handles a cancelled subscription. Returns [ 'success' => true ].

# handleSubscriptionPaused()

Handles a paused subscription. Returns [ 'success' => true ].

# handleSubscriptionResumed()

Handles a resumed subscription. Returns [ 'success' => true ].

# handleSubscriptionInvoiceCreated()

Handles a new subscription invoice. Returns [ 'success' => true ].

# handleTaxesCalculate()

Handles a tax calculation request. Returns array with taxes key (required by Snipcart REST API (opens new window)):

# handleCustomerUpdated()

Handles updated customer details. Returns [ 'success' => true ].

←