The Subscription LifecycleEnrollmentAdd a Subscription to Cart

Helper Methods

Global helper methods available via the og.offers library
View as Markdown

Ordergroove’s offers library registers a global variable, og.offers, that contains a number of useful helper methods.

addOptinChangedCallback

Registers a callback function that is invoked when a user either opts in or opts out of a product offer. Returns the offers module object to enable method chaining.

Arguments

ArgumentDescription
callbackFnA function called when opt-in status changes. The argument passed to the callback is an object containing productId, components, and optedIn.
Example callback argument
1{ "productId": "a123", "components": ["a", "b"], "optedIn": true }

Node/Webpack

1import { addOptinChangedCallback } from '@ordergroove/offers';
2
3function onOptinChanged({ productId, components, optedIn }) {}
4addOptinChangedCallback(onOptinChanged);

clear

Clears the opt-ins from the browser’s local storage. This method should be called upon successful checkout.

1og.offers.clear();

config

Configures the library options for advanced usage or customization. Returns the offers module object to enable method chaining.

Arguments

ArgumentDescription
configObjectA JSON object containing configuration properties

configObject JSON Schema

1{
2  "type": "object",
3  "properties": {
4    "frequencies": {
5      "title": "Available frequencies",
6      "type": "array",
7      "items": {
8        "$ref": "#/definitions/Frequency"
9      },
10      "default": [
11        { "every": 1, "period": 2 },
12        { "every": 2, "period": 2 },
13        {}
14      ],
15      "uniqueItems": true,
16      "minItems": 1,
17      "maxItems": 99
18    },
19    "defaultFrequency": {
20      "title": "Default frequency selection",
21      "$ref": "#/definitions/Frequency"
22    },
23    "offerType": {
24      "title": "Type",
25      "type": "string",
26      "enum": ["radio", "toggle", "select"],
27      "enumNames": ["Radio Button", "Toggle Button", "Select Dropdown"],
28      "default": "radio"
29    }
30  },
31  "required": ["frequencies", "defaultFrequency", "offerType"]
32}
1import { config } from '@ordergroove/offers';
2
3config({
4  frequencies: [
5    { every: 3, period: 2 },
6    { every: 2, period: 2 }
7  ],
8  defaultFrequency: {
9    every: 2,
10    period: 2
11  },
12  offerType: 'radio'
13});

disableOptinChangedCallbacks

Disables all callback functions registered via addOptinChangedCallback.

1import { disableOptinChangedCallbacks } from '@ordergroove/offers';
2
3disableOptinChangedCallbacks();

getOptins

Returns a serialized representation of the products that have been opted in to by the customer, in the format expected by Ordergroove’s Purchase POST endpoint. The optional productIds argument is an array of product IDs for which to return the serialized opt-ins. If not supplied, all opt-ins are returned.

Note that getOptins represents the customer’s action of opting in, not simply whether a product is set to “Default to Subscription”. A default-to-subscription product will not appear in getOptins unless the customer has also clicked the opt-in button.

Arguments

ArgumentDescription
productIdsOptional array of product IDs for which to return the serialized opt-ins. If not supplied, all opt-ins are returned.
1const result = og.offers.getOptins();
2console.log(result);
3
4/**
5[
6  {
7    product: '123',
8    subscription_info: { components: [] },
9    tracking_override: {
10      offer: 'offerId1',
11      every: 2,
12      every_period: 1,
13      session_id: 'sessionId'
14    }
15  },
16  {
17    product: '456',
18    subscription_info: { components: ['a', 'b', 'c'] },
19    tracking_override: {
20      offer: 'offerId2',
21      every: 3,
22      every_period: 1,
23      session_id: 'sessionId'
24    }
25  }
26]
27**/

initialize

Initializes the library. In UMD, this is called as og.offers(...) directly. Returns the offers module object to enable method chaining.

Arguments

ArgumentDescription
merchantIdYour merchant public ID
environmentstaging or production
authUrlThe auth URL endpoint to resolve customer-level auth. Can return JSON or any response that sets a cookie header.
1import { initialize } from '@ordergroove/offers';
2
3initialize('0e5de2bedc5e11e3a2e4bc764e106cf4', 'staging', '/auth');

setLocale

Configures the library locale text. Returns the offers module object to enable method chaining.

PropertyTypeDescriptionDefault
defaultFrequencyCopyStringDefault frequency copyRecommended
frequencyPeriodsObjectFrequency period names{1:"days",2:"weeks",3:"months"}
offerEveryLabelStringSubscribe frequency labelShips Every:
offerOptInLabelStringSubscribe option copySubscribe and get 20% off
offerOptOutLabelStringOne-time option copyOne-time
offerTooltipContentStringTooltip copySubscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change
offerTooltipTriggerStringTooltip link copyMore info
showTooltipBooleanDisplay a tooltipfalse
1import { setLocale } from '@ordergroove/offers';
2
3setLocale({
4  defaultFrequencyCopy: 'Recommended',
5  offerOptInLabel: 'Save Lots and Lots of Money',
6  offerEveryLabel: 'Ships Every: ',
7  offerOptOutLabel: "Don't save money",
8  showTooltip: !0,
9  offerTooltipTrigger: 'More info',
10  offerTooltipContent:
11    'Subscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change.',
12  upsellButtonLabel: 'Add to upcoming subscription order and receive 20% off',
13  upsellButtonContent: 'Add to Next Order on ',
14  upsellModalContent:
15    'Subscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change.',
16  upsellModalOptOutLabel: 'Get one-time',
17  upsellModalOptInLabel: 'Subscribe and get 10% off on every order',
18  upsellModalConfirmLabel: 'Add',
19  frequencyPeriods: {
20    1: 'days',
21    2: 'weeks',
22    3: 'months'
23  }
24});