Payments API

Endpoints for promotional codes, gift card management, and protection plan configuration.

GET /promoGiftCards

Returns all promo codes and gift cards for a customer, or a specific one if promoCode is provided

Parameters

Name	In	Type	Required	Description
`customerId`	query	string	Yes	The customer ID to retrieve promo/gift cards for
`promoCode`	query	string	No	Optional specific promo code to retrieve

Responses

Code	Description
`200`	Promo/gift cards retrieved successfully
`400`	customerId is required
`500`	Internal server error

POST /promoGiftCards

Creates a new promo code or gift card. Requires either $Discount or %Discount in Details.

Request body

Field	Type	Required	Description
`promoCode`	string	Yes
`customerId`	string	Yes
`ExpiryDate`	string	Yes
`Details`	object	Yes
`inventoryIds`	array	No
`locationId`	string	No
`affiliateId`	string	No	Optional affiliate association

Responses

Code	Description
`201`	Promo/gift card created successfully
`400`	Missing required fields or invalid discount
`409`	Promo code already exists for this customer
`500`	Internal server error

PATCH /promoGiftCards

Updates an existing promo/gift card. Supports updating affiliateId and discount fields.

Request body

Field	Type	Required	Description
`promoCode`	string	Yes
`customerId`	string	Yes
`Updates`	object	Yes	Fields to update

Responses

Code	Description
`200`	Promo/gift card updated successfully
`400`	Missing required fields or invalid affiliate
`404`	Promo code not found for this customer
`500`	Internal server error

DELETE /promoGiftCards

Deletes a promo/gift card by promo code and customer ID

Parameters

Name	In	Type	Required	Description
`promoCode`	query	string	Yes	The promo code to delete
`customerId`	query	string	Yes	The customer ID

Responses

Code	Description
`200`	Promo/gift card deleted successfully
`400`	promoCode and customerId are required
`404`	Promo code not found for this customer
`500`	Internal server error

GET /promoGiftCards/search

Uses GSI to find all instances of a promo code across customers (for admin purposes)

Parameters

Name	In	Type	Required	Description
`promoCode`	query	string	Yes	The promo code to search for

Responses

Code	Description
`200`	Search results
`400`	promoCode is required
`500`	Internal server error

Check gift card balance

GET /promoGiftCards/balance

Check the remaining balance of a gift card or usage info for a promo code

Parameters

Name	In	Type	Required	Description
`promoCode`	query	string	Yes	The promo/gift card code to check
`customerId`	query	string	No	Optional customer ID for faster lookup

Responses

Code	Description
`200`	Balance information retrieved successfully
`400`	promoCode is required
`404`	Gift card or promo code not found
`500`	Internal server error

POST /promoGiftCards/use

Tracks promo code usage and affiliate commissions when a promo code is applied

Request body

Field	Type	Required	Description
`promoCode`	string	Yes
`customerId`	string	Yes	The customer who owns the promo code
`orderAmount`	number	Yes	The order amount to apply the discount to
`userId`	string	No	Optional - the user applying the promo code

Responses

Code	Description
`200`	Promo code applied successfully
`400`	Missing required fields, expired promo code, or usage limit reached
`404`	Promo code not found for this customer
`500`	Internal server error

GET /promoGiftCards/affiliate/{affiliateId}

Retrieves all promo codes associated with a specific affiliate and analytics

Parameters

Name	In	Type	Required	Description
`affiliateId`	path	string	Yes	The affiliate ID
`customerId`	query	string	Yes	The customer ID

Responses

Code	Description
`200`	Affiliate promo codes retrieved successfully
`400`	customerId is required or invalid affiliate
`500`	Internal server error

Public Gift Cards

Create payment intent for gift card

POST /public/gift-card/create-payment-intent

Creates a Stripe payment intent for purchasing a gift card

Request body

Field	Type	Required	Description
`amount`	number	Yes	Total amount including fees
`giftCardAmount`	number	No	Gift card value amount
`customerId`	string	Yes
`giftCardCode`	string	Yes
`recipientName`	string	No
`recipientEmail`	string	No
`message`	string	No
`expiryDate`	string	No
`currency`	string	No
`connectAccountId`	string	No	Stripe Connect account ID for transfer
`applicationFeeAmount`	number	No	Platform fee amount

Responses

Code	Description
`200`	Payment intent created successfully
`400`	Missing required fields or invalid amount
`500`	Internal server error

Confirm gift card payment

POST /public/gift-card/confirm-payment

Confirms payment and creates the gift card after successful Stripe payment

Request body

Field	Type	Required	Description
`paymentIntentId`	string	Yes	The Stripe payment intent ID to confirm

Responses

Code	Description
`201`	Gift card created successfully
`400`	Payment intent ID required or payment not successful
`409`	Gift card code already exists
`500`	Internal server error

Stripe webhook handler

POST /public/gift-card/webhook

Stripe webhook endpoint to handle payment events for gift cards (backup verification)

Responses

Code	Description
`200`	Webhook received and processed
`400`	Webhook not configured or invalid signature

Send gift card email

POST /public/gift-card/send-email

Sends a gift card via email to the recipient with redemption instructions

Request body

Field	Type	Required
`giftCardCode`	string	Yes
`giftCardAmount`	number	Yes
`recipientEmail`	string	Yes
`recipientName`	string	No
`message`	string	No
`expiryDate`	string	No
`customerId`	string	Yes

Responses

Code	Description
`200`	Email sent successfully
`400`	Missing required fields or invalid email format
`500`	Email service error or failed to send

Charge saved card for gift card

POST /public/gift-card/charge-saved-card

Charges a saved payment method for gift card purchase

Request body

Field	Type	Required	Description
`paymentMethodId`	string	Yes	Stripe payment method ID
`amount`	number	Yes
`currency`	string	No
`customerId`	string	Yes
`stripeCustomerId`	string	No
`description`	string	No
`metadata`	object	No
`connectAccountId`	string	No	Stripe Connect account ID for transfer
`applicationFeeAmount`	number	No	Platform fee amount

Responses

Code	Description
`200`	Payment processed successfully
`400`	Missing required fields or invalid amount
`500`	Internal server error

Protection Plans

Get available protection plans

GET /api/v2/protection-plans

Returns protection plans for a specific industry

Parameters

Name	In	Type	Required	Description
`industry`	query	string	No	Industry type (defaults to marine)
`locationId`	query	string	No	Location ID to filter by enabled plans
`includeInactive`	query	boolean	No	Include inactive plans (admin only)

Responses

Code	Description
`200`	List of protection plans
`500`	Server error

Get available protection bundles

GET /api/v2/protection-bundles

Returns protection bundles for a specific industry

Parameters

Name	In	Type	Required	Description
`industry`	query	string	No	Industry type (defaults to marine)
`locationId`	query	string	No	Location ID to filter by enabled bundles

Responses

Code	Description
`200`	List of protection bundles
`500`	Server error

Get a specific protection plan by code

GET /api/v2/protection-plans/{planCode}

Parameters

Name	In	Type	Required	Description
`planCode`	path	string	Yes

Responses

Code	Description
`200`	Protection plan details
`404`	Plan not found
`500`	Server error

Get a specific protection bundle by code with included plans

GET /api/v2/protection-bundles/{bundleCode}

Parameters

Name	In	Type	Required	Description
`bundleCode`	path	string	Yes

Responses

Code	Description
`200`	Protection bundle details with included plans
`404`	Bundle not found
`500`	Server error

Get protection settings for a location

GET /api/v2/locations/{locationId}/protection-settings

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes

Responses

Code	Description
`200`	Location protection settings
`404`	Settings not found (returns defaults)
`500`	Server error

Update protection settings for a location

PUT /api/v2/locations/{locationId}/protection-settings

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes

Request body

Field	Type	Required
`industry`	string	No
`enabledPlanCodes`	array	No
`enabledBundleCodes`	array	No
`planOverrides`	object	No

Responses

Code	Description
`200`	Settings updated successfully
`400`	Invalid request
`500`	Server error

Enable a plan for a location

POST /api/v2/locations/{locationId}/protection-settings/plan/{planCode}

Responses

Code	Description
`200`	Plan enabled

Disable a plan for a location

DELETE /api/v2/locations/{locationId}/protection-settings/plan/{planCode}

Responses

Code	Description
`200`	Plan disabled

Enable a bundle for a location

POST /api/v2/locations/{locationId}/protection-settings/bundle/{bundleCode}

Disable a bundle for a location

DELETE /api/v2/locations/{locationId}/protection-settings/bundle/{bundleCode}

Set pricing override for a plan at a location

PUT /api/v2/locations/{locationId}/protection-settings/override/{planCode}

Request body

Field	Type	Required	Description
`percentage`	number	No
`maxCap`	number	No

Remove pricing override for a plan at a location

DELETE /api/v2/locations/{locationId}/protection-settings/override/{planCode}

Promo & Gift Cards .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get promo/gift cards for a customer .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Create a new promo/gift card .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Update a promo/gift card .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Delete a promo/gift card .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Search promo codes across all customers .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Check gift card balance .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Apply a promo code .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get promo codes for an affiliate .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Public Gift Cards .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Create payment intent for gift card .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Confirm gift card payment .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Stripe webhook handler .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Send gift card email .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Charge saved card for gift card .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Protection Plans .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get available protection plans .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get available protection bundles .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get a specific protection plan by code .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get a specific protection bundle by code with included plans .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Get protection settings for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Update protection settings for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Enable a plan for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Disable a plan for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Enable a bundle for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Disable a bundle for a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Set pricing override for a plan at a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Remove pricing override for a plan at a location .docs-heading:hover .heading-anchor { opacity: 1; } .heading-anchor:focus { opacity: 1; }

Promo & Gift Cards

Get promo/gift cards for a customer

Create a new promo/gift card

Update a promo/gift card

Delete a promo/gift card

Search promo codes across all customers

Check gift card balance

Apply a promo code

Get promo codes for an affiliate

Public Gift Cards

Create payment intent for gift card

Confirm gift card payment

Stripe webhook handler

Send gift card email

Charge saved card for gift card

Protection Plans

Get available protection plans

Get available protection bundles

Get a specific protection plan by code

Get a specific protection bundle by code with included plans

Get protection settings for a location

Update protection settings for a location

Enable a plan for a location

Disable a plan for a location

Enable a bundle for a location

Disable a bundle for a location

Set pricing override for a plan at a location

Remove pricing override for a plan at a location