> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ordergroove.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server. # Helper Methods 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 | Argument | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `callbackFn` | A function called when opt-in status changes. The argument passed to the callback is an object containing `productId`, `components`, and `optedIn`. | ```json title="Example callback argument" { "productId": "a123", "components": ["a", "b"], "optedIn": true } ``` ### Node/Webpack ```javascript import { addOptinChangedCallback } from '@ordergroove/offers'; function onOptinChanged({ productId, components, optedIn }) {} addOptinChangedCallback(onOptinChanged); ``` *** ## clear Clears the opt-ins from the browser's local storage. This method should be called upon successful checkout. ```javascript og.offers.clear(); ``` *** ## config Configures the library options for advanced usage or customization. Returns the offers module object to enable method chaining. ### Arguments | Argument | Description | | -------------- | ------------------------------------------------- | | `configObject` | A JSON object containing configuration properties | ### configObject JSON Schema ```json { "type": "object", "properties": { "frequencies": { "title": "Available frequencies", "type": "array", "items": { "$ref": "#/definitions/Frequency" }, "default": [ { "every": 1, "period": 2 }, { "every": 2, "period": 2 }, {} ], "uniqueItems": true, "minItems": 1, "maxItems": 99 }, "defaultFrequency": { "title": "Default frequency selection", "$ref": "#/definitions/Frequency" }, "offerType": { "title": "Type", "type": "string", "enum": ["radio", "toggle", "select"], "enumNames": ["Radio Button", "Toggle Button", "Select Dropdown"], "default": "radio" } }, "required": ["frequencies", "defaultFrequency", "offerType"] } ``` ```javascript title="Node/Webpack" import { config } from '@ordergroove/offers'; config({ frequencies: [ { every: 3, period: 2 }, { every: 2, period: 2 } ], defaultFrequency: { every: 2, period: 2 }, offerType: 'radio' }); ``` ```javascript title="UMD" og.offers('0e5de2bedc5e11e3a2e4bc764e106cf4', 'staging', '/auth').config({ frequencies: [ { every: 3, period: 2 }, { every: 2, period: 2 } ], defaultFrequency: { every: 2, period: 2 }, offerType: 'radio' }); ``` *** ## disableOptinChangedCallbacks Disables all callback functions registered via `addOptinChangedCallback`. ```javascript title="Node/Webpack" import { disableOptinChangedCallbacks } from '@ordergroove/offers'; disableOptinChangedCallbacks(); ``` ```javascript title="UMD" og.offers(...).addOptinChangedCallback(() => {}); ``` *** ## 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 | Argument | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------- | | `productIds` | Optional array of product IDs for which to return the serialized opt-ins. If not supplied, all opt-ins are returned. | ```javascript title="Multiple Products" const result = og.offers.getOptins(); console.log(result); /** [ { product: '123', subscription_info: { components: [] }, tracking_override: { offer: 'offerId1', every: 2, every_period: 1, session_id: 'sessionId' } }, { product: '456', subscription_info: { components: ['a', 'b', 'c'] }, tracking_override: { offer: 'offerId2', every: 3, every_period: 1, session_id: 'sessionId' } } ] **/ ``` ```javascript title="Single Product" const result = og.offers.getOptins(['123']); console.log(result); /** [ { product: '123', subscription_info: { components: [] }, tracking_override: { offer: 'offerId1', every: 2, every_period: 1, session_id: 'sessionId' } } ] **/ ``` *** ## initialize Initializes the library. In UMD, this is called as `og.offers(...)` directly. Returns the offers module object to enable method chaining. ### Arguments | Argument | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `merchantId` | Your merchant public ID | | `environment` | `staging` or `production` | | `authUrl` | The auth URL endpoint to resolve customer-level auth. Can return JSON or any response that sets a cookie header. | ```javascript title="Node/Webpack" import { initialize } from '@ordergroove/offers'; initialize('0e5de2bedc5e11e3a2e4bc764e106cf4', 'staging', '/auth'); ``` ```javascript title="UMD" og.offers('0e5de2bedc5e11e3a2e4bc764e106cf4', 'staging', '/auth'); ``` *** ## setLocale Configures the library locale text. Returns the offers module object to enable method chaining. | Property | Type | Description | Default | | ---------------------- | ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `defaultFrequencyCopy` | String | Default frequency copy | `Recommended` | | `frequencyPeriods` | Object | Frequency period names | `{1:"days",2:"weeks",3:"months"}` | | `offerEveryLabel` | String | Subscribe frequency label | `Ships Every:` | | `offerOptInLabel` | String | Subscribe option copy | `Subscribe and get 20% off` | | `offerOptOutLabel` | String | One-time option copy | `One-time` | | `offerTooltipContent` | String | Tooltip copy | `Subscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change` | | `offerTooltipTrigger` | String | Tooltip link copy | `More info` | | `showTooltip` | Boolean | Display a tooltip | `false` | ```javascript title="Node/Webpack" import { setLocale } from '@ordergroove/offers'; setLocale({ defaultFrequencyCopy: 'Recommended', offerOptInLabel: 'Save Lots and Lots of Money', offerEveryLabel: 'Ships Every: ', offerOptOutLabel: "Don't save money", showTooltip: !0, offerTooltipTrigger: 'More info', offerTooltipContent: 'Subscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change.', upsellButtonLabel: 'Add to upcoming subscription order and receive 20% off', upsellButtonContent: 'Add to Next Order on ', upsellModalContent: 'Subscribe to this product and have it conveniently delivered to you at the frequency you choose! Read the FAQ here. Promotion subject to change.', upsellModalOptOutLabel: 'Get one-time', upsellModalOptInLabel: 'Subscribe and get 10% off on every order', upsellModalConfirmLabel: 'Add', frequencyPeriods: { 1: 'days', 2: 'weeks', 3: 'months' } }); ``` ```javascript title="UMD" og.offers(...).config(...).setLocale({ ... }); ```