acpcart

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package acpcart serves the seller-hosted ACP Cart API.

Carts provide a lightweight pre-checkout phase for item collection without payment configuration or a status lifecycle. Totals are estimates until checkout. Updates replace the complete mutable cart state.

Implement Provider and pass it to NewHandler.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIVersion 

type APIVersion = string

APIVersion defines model for APIVersion.

type AcceptLanguage 

type AcceptLanguage = string

AcceptLanguage defines model for AcceptLanguage.

type Authorization 

type Authorization = string

Authorization defines model for Authorization.

type BadRequest 

type BadRequest = Error

BadRequest Protocol-level error returned in 4xx/5xx responses when the server cannot return a valid CheckoutSession at all (e.g. malformed request or unexpected failure). Use Error—not MessageError—when there is no valid session state to return. type semantics: invalid_request — malformed request, missing required fields, invalid JSON, or idempotency violations (codes: idempotency_key_required, idempotency_in_flight, idempotency_conflict); processing_error — unexpected server-side failure; service_unavailable — temporary unavailability.

type Buyer 

type Buyer struct {
	// AccountType Type of buyer account
	AccountType *BuyerAccountType `json:"account_type,omitempty"`

	// AuthenticationStatus Buyer's authentication status
	AuthenticationStatus *BuyerAuthenticationStatus `json:"authentication_status,omitempty"`

	// Company Company information for business buyers
	Company *CompanyInfo `json:"company,omitempty"`

	// CustomerId Merchant's internal customer identifier
	CustomerId *string `json:"customer_id,omitempty"`

	// Email Buyer's email address
	Email openapi_types.Email `json:"email"`

	// FirstName Buyer's first name
	FirstName *string `json:"first_name,omitempty"`

	// FullName Buyer's full name
	FullName *string `json:"full_name,omitempty"`

	// LastName Buyer's last name
	LastName *string `json:"last_name,omitempty"`

	// Loyalty Loyalty program information
	Loyalty *LoyaltyInfo `json:"loyalty,omitempty"`

	// PhoneNumber Buyer's phone number
	PhoneNumber *string `json:"phone_number,omitempty"`

	// TaxExemption Tax exemption details
	TaxExemption *TaxExemption `json:"tax_exemption,omitempty"`
}

Buyer Information about the buyer including contact details, company info, and loyalty status

type BuyerAccountType 

type BuyerAccountType string

BuyerAccountType Type of buyer account 

const (
	BuyerAccountTypeBusiness   BuyerAccountType = "business"
	BuyerAccountTypeGuest      BuyerAccountType = "guest"
	BuyerAccountTypeRegistered BuyerAccountType = "registered"
)

Defines values for BuyerAccountType.

func (BuyerAccountType) Valid 

func (e BuyerAccountType) Valid() bool

Valid indicates whether the value is a known member of the BuyerAccountType enum.

type BuyerAuthenticationStatus 

type BuyerAuthenticationStatus string

BuyerAuthenticationStatus Buyer's authentication status 

const (
	BuyerAuthenticationStatusAuthenticated  BuyerAuthenticationStatus = "authenticated"
	BuyerAuthenticationStatusGuest          BuyerAuthenticationStatus = "guest"
	BuyerAuthenticationStatusRequiresSignin BuyerAuthenticationStatus = "requires_signin"
)

Defines values for BuyerAuthenticationStatus.

func (BuyerAuthenticationStatus) Valid 

func (e BuyerAuthenticationStatus) Valid() bool

Valid indicates whether the value is a known member of the BuyerAuthenticationStatus enum.

type CancelCartJSONBody 

type CancelCartJSONBody = map[string]interface{}

CancelCartJSONBody defines parameters for CancelCart.

type CancelCartJSONRequestBody 

type CancelCartJSONRequestBody = CancelCartJSONBody

CancelCartJSONRequestBody defines body for CancelCart for application/json ContentType.

type CancelCartParams 

type CancelCartParams struct {
	// Authorization Bearer token for API authentication
	Authorization Authorization `json:"Authorization"`

	// IdempotencyKey Idempotency key. MUST be present on all POST requests. Opaque string, max 255 characters. UUID v4 recommended.
	IdempotencyKey IdempotencyKey `json:"Idempotency-Key"`
	RequestId      *RequestId     `json:"Request-Id,omitempty"`
	APIVersion     APIVersion     `json:"API-Version"`
}

CancelCartParams defines parameters for CancelCart.

type Cart 

type Cart struct {
	// Buyer Buyer information, if provided.
	Buyer *Buyer `json:"buyer,omitempty"`

	// ContinueUrl URL for cart handoff, sharing, or session recovery.
	ContinueUrl *string `json:"continue_url,omitempty"`

	// Currency ISO 4217 currency code. Determined by the seller based on context or request.
	Currency string `json:"currency"`

	// ExpiresAt RFC 3339 timestamp when the cart expires.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// Id Unique cart identifier, server-generated.
	Id string `json:"id"`

	// LineItems Cart line items. Same structure as checkout line items.
	LineItems []LineItem `json:"line_items"`

	// Messages Validation messages, warnings, or informational notices (e.g., low stock, price changes).
	Messages *[]Cart_Messages_Item `json:"messages,omitempty"`

	// Totals Estimated cost breakdown. May be partial (e.g., tax omitted if address is unknown). Totals are estimates until checkout.
	Totals []Total `json:"totals"`
}

Cart A shopping cart with estimated pricing. Carts provide a lightweight pre-checkout phase for item collection without payment configuration or status lifecycle.

type CartCreateRequest 

type CartCreateRequest struct {
	// Buyer Buyer information for personalized estimates.
	Buyer *Buyer `json:"buyer,omitempty"`

	// LineItems Items to add to the cart.
	LineItems []Item `json:"line_items"`

	// Locale Locale code for content localization (e.g., 'en-US').
	Locale *string `json:"locale,omitempty"`
}

CartCreateRequest Request to create a new cart.

type CartId 

type CartId = string

CartId defines model for CartId.

type CartNotFound 

type CartNotFound = Error

CartNotFound Protocol-level error returned in 4xx/5xx responses when the server cannot return a valid CheckoutSession at all (e.g. malformed request or unexpected failure). Use Error—not MessageError—when there is no valid session state to return. type semantics: invalid_request — malformed request, missing required fields, invalid JSON, or idempotency violations (codes: idempotency_key_required, idempotency_in_flight, idempotency_conflict); processing_error — unexpected server-side failure; service_unavailable — temporary unavailability.

type CartUpdateRequest 

type CartUpdateRequest struct {
	// Buyer Updated buyer information.
	Buyer *Buyer `json:"buyer,omitempty"`

	// LineItems Complete list of items (replaces existing cart contents).
	LineItems []Item `json:"line_items"`
}

CartUpdateRequest Request to update a cart. Full replacement — the agent MUST send the complete desired cart state.

type Cart_Messages_Item 

type Cart_Messages_Item struct {
	// contains filtered or unexported fields
}

Cart_Messages_Item defines model for Cart.messages.Item.

func (Cart_Messages_Item) AsMessageError 

func (t Cart_Messages_Item) AsMessageError() (MessageError, error)

AsMessageError returns the union data inside the Cart_Messages_Item as a MessageError

func (Cart_Messages_Item) AsMessageInfo 

func (t Cart_Messages_Item) AsMessageInfo() (MessageInfo, error)

AsMessageInfo returns the union data inside the Cart_Messages_Item as a MessageInfo

func (Cart_Messages_Item) AsMessageWarning 

func (t Cart_Messages_Item) AsMessageWarning() (MessageWarning, error)

AsMessageWarning returns the union data inside the Cart_Messages_Item as a MessageWarning

func (*Cart_Messages_Item) FromMessageError 

func (t *Cart_Messages_Item) FromMessageError(v MessageError) error

FromMessageError overwrites any union data inside the Cart_Messages_Item as the provided MessageError

func (*Cart_Messages_Item) FromMessageInfo 

func (t *Cart_Messages_Item) FromMessageInfo(v MessageInfo) error

FromMessageInfo overwrites any union data inside the Cart_Messages_Item as the provided MessageInfo

func (*Cart_Messages_Item) FromMessageWarning 

func (t *Cart_Messages_Item) FromMessageWarning(v MessageWarning) error

FromMessageWarning overwrites any union data inside the Cart_Messages_Item as the provided MessageWarning

func (Cart_Messages_Item) MarshalJSON 

func (t Cart_Messages_Item) MarshalJSON() ([]byte, error)

func (*Cart_Messages_Item) MergeMessageError 

func (t *Cart_Messages_Item) MergeMessageError(v MessageError) error

MergeMessageError performs a merge with any union data inside the Cart_Messages_Item, using the provided MessageError

func (*Cart_Messages_Item) MergeMessageInfo 

func (t *Cart_Messages_Item) MergeMessageInfo(v MessageInfo) error

MergeMessageInfo performs a merge with any union data inside the Cart_Messages_Item, using the provided MessageInfo

func (*Cart_Messages_Item) MergeMessageWarning 

func (t *Cart_Messages_Item) MergeMessageWarning(v MessageWarning) error

MergeMessageWarning performs a merge with any union data inside the Cart_Messages_Item, using the provided MessageWarning

func (*Cart_Messages_Item) UnmarshalJSON 

func (t *Cart_Messages_Item) UnmarshalJSON(b []byte) error

type CompanyInfo 

type CompanyInfo struct {
	// CostCenter Cost center code for internal accounting
	CostCenter *string `json:"cost_center,omitempty"`

	// Department Department within the organization
	Department *string `json:"department,omitempty"`

	// Name Company or organization name
	Name string `json:"name"`

	// TaxId Business tax identification number
	TaxId *string `json:"tax_id,omitempty"`
}

CompanyInfo Information about a company or organization associated with the buyer

type ContentType 

type ContentType = string

ContentType defines model for ContentType.

type CreateCartJSONRequestBody 

type CreateCartJSONRequestBody = CartCreateRequest

CreateCartJSONRequestBody defines body for CreateCart for application/json ContentType.

type CreateCartParams 

type CreateCartParams struct {
	// Authorization Bearer token for API authentication
	Authorization  Authorization   `json:"Authorization"`
	ContentType    ContentType     `json:"Content-Type"`
	AcceptLanguage *AcceptLanguage `json:"Accept-Language,omitempty"`

	// IdempotencyKey Idempotency key. MUST be present on all POST requests. Opaque string, max 255 characters. UUID v4 recommended.
	IdempotencyKey IdempotencyKey `json:"Idempotency-Key"`
	RequestId      *RequestId     `json:"Request-Id,omitempty"`
	APIVersion     APIVersion     `json:"API-Version"`
}

CreateCartParams defines parameters for CreateCart.

type CustomAttribute 

type CustomAttribute struct {
	// DisplayName Human-readable label for the attribute
	DisplayName string `json:"display_name"`

	// Value Attribute value
	Value string `json:"value"`
}

CustomAttribute Custom key-value attribute for merchant-specific metadata on line items

type DimensionsInfo 

type DimensionsInfo struct {
	// Height Height dimension
	Height float32 `json:"height"`

	// Length Length dimension
	Length float32 `json:"length"`

	// Unit Unit of measurement for dimensions
	Unit DimensionsInfoUnit `json:"unit"`

	// Width Width dimension
	Width float32 `json:"width"`
}

DimensionsInfo Physical dimensions of a product with unit of measurement

type DimensionsInfoUnit 

type DimensionsInfoUnit string

DimensionsInfoUnit Unit of measurement for dimensions 

const (
	Cm DimensionsInfoUnit = "cm"
	In DimensionsInfoUnit = "in"
)

Defines values for DimensionsInfoUnit.

func (DimensionsInfoUnit) Valid 

func (e DimensionsInfoUnit) Valid() bool

Valid indicates whether the value is a known member of the DimensionsInfoUnit enum.

type Disclosure 

type Disclosure struct {
	// Content The disclosure text content. When content_type is 'markdown', this MUST be valid CommonMark with no raw HTML. Agents MUST render using a CommonMark-compliant parser with raw HTML output disabled or sanitized.
	Content string `json:"content"`

	// ContentType Format of the disclosure content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting.
	ContentType DisclosureContentType `json:"content_type"`

	// Type Type of disclosure
	Type DisclosureType `json:"type"`
}

Disclosure Legal disclosure or terms that must be acknowledged by the buyer

type DisclosureContentType 

type DisclosureContentType string

DisclosureContentType Format of the disclosure content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting. 

const (
	DisclosureContentTypeMarkdown DisclosureContentType = "markdown"
	DisclosureContentTypePlain    DisclosureContentType = "plain"
)

Defines values for DisclosureContentType.

func (DisclosureContentType) Valid 

func (e DisclosureContentType) Valid() bool

Valid indicates whether the value is a known member of the DisclosureContentType enum.

type DisclosureType 

type DisclosureType string

DisclosureType Type of disclosure 

const (
	Disclaimer DisclosureType = "disclaimer"
)

Defines values for DisclosureType.

func (DisclosureType) Valid 

func (e DisclosureType) Valid() bool

Valid indicates whether the value is a known member of the DisclosureType enum.

type DiscountDetail 

type DiscountDetail struct {
	// Amount Discount amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
	Amount int `json:"amount"`

	// Code Discount code if applicable
	Code *string `json:"code,omitempty"`

	// Description Human-readable discount description
	Description *string `json:"description,omitempty"`

	// Source Source of the discount
	Source *DiscountDetailSource `json:"source,omitempty"`

	// Type Type of discount
	Type DiscountDetailType `json:"type"`
}

DiscountDetail Information about a discount applied to the checkout or a specific item

type DiscountDetailSource 

type DiscountDetailSource string

DiscountDetailSource Source of the discount 

const (
	Automatic DiscountDetailSource = "automatic"
	Coupon    DiscountDetailSource = "coupon"
	Loyalty   DiscountDetailSource = "loyalty"
)

Defines values for DiscountDetailSource.

func (DiscountDetailSource) Valid 

func (e DiscountDetailSource) Valid() bool

Valid indicates whether the value is a known member of the DiscountDetailSource enum.

type DiscountDetailType 

type DiscountDetailType string

DiscountDetailType Type of discount 

const (
	Bogo       DiscountDetailType = "bogo"
	Fixed      DiscountDetailType = "fixed"
	Percentage DiscountDetailType = "percentage"
	Volume     DiscountDetailType = "volume"
)

Defines values for DiscountDetailType.

func (DiscountDetailType) Valid 

func (e DiscountDetailType) Valid() bool

Valid indicates whether the value is a known member of the DiscountDetailType enum.

type Error 

type Error struct {
	// Code Implementation-defined error code
	Code string `json:"code"`

	// Message Human-readable error message
	Message string `json:"message"`

	// Param RFC 9535 JSONPath (optional)
	Param *string `json:"param,omitempty"`

	// SupportedVersions List of API versions supported by the server, ordered by preference (newest first). Only included in version-related errors.
	SupportedVersions *[]string `json:"supported_versions,omitempty"`

	// Type Error type indicating the category of protocol-level error
	Type ErrorType `json:"type"`
}

Error Protocol-level error returned in 4xx/5xx responses when the server cannot return a valid CheckoutSession at all (e.g. malformed request or unexpected failure). Use Error—not MessageError—when there is no valid session state to return. type semantics: invalid_request — malformed request, missing required fields, invalid JSON, or idempotency violations (codes: idempotency_key_required, idempotency_in_flight, idempotency_conflict); processing_error — unexpected server-side failure; service_unavailable — temporary unavailability.

type ErrorType 

type ErrorType string

ErrorType Error type indicating the category of protocol-level error 

const (
	InvalidRequest     ErrorType = "invalid_request"
	ProcessingError    ErrorType = "processing_error"
	ServiceUnavailable ErrorType = "service_unavailable"
)

Defines values for ErrorType.

func (ErrorType) Valid 

func (e ErrorType) Valid() bool

Valid indicates whether the value is a known member of the ErrorType enum.

type GetCartParams 

type GetCartParams struct {
	// Authorization Bearer token for API authentication
	Authorization  Authorization   `json:"Authorization"`
	AcceptLanguage *AcceptLanguage `json:"Accept-Language,omitempty"`
	RequestId      *RequestId      `json:"Request-Id,omitempty"`
	APIVersion     APIVersion      `json:"API-Version"`
}

GetCartParams defines parameters for GetCart.

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler exposes the ACP cart API over net/http.

func NewHandler 

func NewHandler(provider Provider, authorizer acpauth.Authorizer, opts ...Option) *Handler

NewHandler returns a Handler that serves the ACP cart API.

Example 
package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/sumup/acp/acpauth"
	"github.com/sumup/acp/acpcart"
)

type cartProvider struct{}

func (cartProvider) CreateCart(context.Context, acpcart.CartCreateRequest) (*acpcart.Cart, error) {
	return nil, errors.ErrUnsupported
}

func (cartProvider) GetCart(context.Context, string) (*acpcart.Cart, error) {
	return nil, errors.ErrUnsupported
}

func (cartProvider) UpdateCart(context.Context, string, acpcart.CartUpdateRequest) (*acpcart.Cart, error) {
	return nil, errors.ErrUnsupported
}

func (cartProvider) CancelCart(context.Context, string) (*acpcart.Cart, error) {
	return nil, errors.ErrUnsupported
}

func main() {
	handler := acpcart.NewHandler(
		cartProvider{},
		acpauth.StaticTokenAuthorizer("api_key_123"),
	)

	fmt.Printf("%T\n", handler)
}

Output:
*acpcart.Handler

func (*Handler) ServeHTTP 

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP dispatches cart requests to the configured ACP routes.

type IdempotencyKey 

type IdempotencyKey = string

IdempotencyKey defines model for IdempotencyKey.

type Item 

type Item struct {
	// Id Unique identifier for the item
	Id string `json:"id"`

	// Name Display name of the item
	Name *string `json:"name,omitempty"`

	// UnitAmount Price per unit in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
	UnitAmount *int `json:"unit_amount,omitempty"`
}

Item A purchasable item with variant options (e.g., size, color) and quantity

type LineItem 

type LineItem struct {
	// AvailabilityStatus Current availability status of the item
	AvailabilityStatus *LineItemAvailabilityStatus `json:"availability_status,omitempty"`

	// AvailableQuantity Quantity currently available for purchase
	AvailableQuantity *int `json:"available_quantity,omitempty"`

	// Category Product category
	Category *string `json:"category,omitempty"`

	// CustomAttributes Custom attributes specific to this line item
	CustomAttributes *[]CustomAttribute `json:"custom_attributes,omitempty"`

	// Description Detailed description of the line item
	Description *string `json:"description,omitempty"`

	// Dimensions Dimensions for the item
	Dimensions *DimensionsInfo `json:"dimensions,omitempty"`

	// Disclosures Legal disclosures or disclaimers for this item
	Disclosures *[]Disclosure `json:"disclosures,omitempty"`

	// DiscountDetails Line-item level discount details
	DiscountDetails *[]DiscountDetail `json:"discount_details,omitempty"`

	// FulfillableOn RFC 3339 timestamp when item becomes available for fulfillment
	FulfillableOn *time.Time `json:"fulfillable_on,omitempty"`

	// Id Unique identifier for the line item
	Id string `json:"id"`

	// Images Array of image URLs for this line item
	Images *[]string `json:"images,omitempty"`

	// Item Reference to the item being purchased
	Item Item `json:"item"`

	// MarketplaceSellerDetails Seller details for marketplace items
	MarketplaceSellerDetails *MarketplaceSellerDetails `json:"marketplace_seller_details,omitempty"`

	// MaxQuantityPerOrder Maximum quantity allowed per order
	MaxQuantityPerOrder *int `json:"max_quantity_per_order,omitempty"`

	// Name Display name of the line item
	Name *string `json:"name,omitempty"`

	// ParentId Reference to parent line item for bundled products
	ParentId *string `json:"parent_id,omitempty"`

	// ProductId Merchant's product identifier
	ProductId *string `json:"product_id,omitempty"`

	// Quantity Number of units for this line item
	Quantity int `json:"quantity"`

	// Sku Stock keeping unit identifier
	Sku *string `json:"sku,omitempty"`

	// Tags Product tags or labels
	Tags *[]string `json:"tags,omitempty"`

	// TaxExempt Whether this line item is tax exempt
	TaxExempt *bool `json:"tax_exempt,omitempty"`

	// TaxExemptionReason Reason for tax exemption if applicable
	TaxExemptionReason *string `json:"tax_exemption_reason,omitempty"`

	// Totals Line-item level totals breakdown including base_amount, discount, subtotal, tax, and total
	Totals []Total `json:"totals"`

	// UnitAmount The unit price of the line item in the smallest currency unit (e.g., cents for USD)
	UnitAmount *int `json:"unit_amount,omitempty"`

	// VariantId Product variant identifier
	VariantId *string `json:"variant_id,omitempty"`

	// VariantOptions Selected product variant options (e.g., size, color)
	VariantOptions *[]VariantOption `json:"variant_options,omitempty"`

	// Weight Weight information for the item
	Weight *WeightInfo `json:"weight,omitempty"`
}

LineItem A line item in the checkout representing a product with pricing, discounts, and fulfillment details

type LineItemAvailabilityStatus 

type LineItemAvailabilityStatus string

LineItemAvailabilityStatus Current availability status of the item 

const (
	LineItemAvailabilityStatusBackorder  LineItemAvailabilityStatus = "backorder"
	LineItemAvailabilityStatusInStock    LineItemAvailabilityStatus = "in_stock"
	LineItemAvailabilityStatusLowStock   LineItemAvailabilityStatus = "low_stock"
	LineItemAvailabilityStatusOutOfStock LineItemAvailabilityStatus = "out_of_stock"
	LineItemAvailabilityStatusPreOrder   LineItemAvailabilityStatus = "pre_order"
)

Defines values for LineItemAvailabilityStatus.

func (LineItemAvailabilityStatus) Valid 

func (e LineItemAvailabilityStatus) Valid() bool

Valid indicates whether the value is a known member of the LineItemAvailabilityStatus enum.

type LoyaltyInfo 

type LoyaltyInfo struct {
	// MemberSince RFC 3339 timestamp when the customer joined the loyalty program
	MemberSince *time.Time `json:"member_since,omitempty"`

	// PointsBalance Current loyalty points balance
	PointsBalance *int `json:"points_balance,omitempty"`

	// Tier Loyalty program tier level
	Tier *string `json:"tier,omitempty"`
}

LoyaltyInfo Loyalty program information including membership details and rewards balance

type MarketplaceSellerDetails 

type MarketplaceSellerDetails struct {
	// Name Name of the marketplace seller or vendor
	Name string `json:"name"`
}

MarketplaceSellerDetails Information about a third-party seller in a marketplace model

type MessageError 

type MessageError struct {
	// Code Error code indicating the type of error
	Code MessageErrorCode `json:"code"`

	// Content Error message text. When content_type is 'markdown', this MUST be valid CommonMark with no raw HTML. Agents MUST render using a CommonMark-compliant parser with raw HTML output disabled or sanitized.
	Content string `json:"content"`

	// ContentType Format of the error message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting.
	ContentType MessageErrorContentType `json:"content_type"`

	// Param RFC 9535 JSONPath
	Param *string `json:"param,omitempty"`

	// Resolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize.
	Resolution *MessageErrorResolution `json:"resolution,omitempty"`

	// Severity Severity level of this error
	Severity *MessageErrorSeverity `json:"severity,omitempty"`

	// Type Message type discriminator
	Type MessageErrorType `json:"type"`
}

MessageError Business-logic error within a valid CheckoutSession response. Used in messages[] on 2xx responses when the session is valid but has actionable issues (e.g. status "not_ready_for_payment"). The agent can respond by asking the buyer for corrections or trying alternatives. Use MessageError—not Error—when you can return a valid CheckoutSession and the problem is conversational (e.g. invalid email → code "invalid" and param "$.buyer.email"; out of stock → code "out_of_stock" and param "$.items[0]").

type MessageErrorCode 

type MessageErrorCode string

MessageErrorCode Error code indicating the type of error 

const (
	MessageErrorCodeAgeVerificationRequired MessageErrorCode = "age_verification_required"
	MessageErrorCodeApprovalRequired        MessageErrorCode = "approval_required"
	MessageErrorCodeConflict                MessageErrorCode = "conflict"
	MessageErrorCodeCouponExpired           MessageErrorCode = "coupon_expired"
	MessageErrorCodeCouponInvalid           MessageErrorCode = "coupon_invalid"
	MessageErrorCodeExpired                 MessageErrorCode = "expired"
	MessageErrorCodeInterventionRequired    MessageErrorCode = "intervention_required"
	MessageErrorCodeInvalid                 MessageErrorCode = "invalid"
	MessageErrorCodeLowStock                MessageErrorCode = "low_stock"
	MessageErrorCodeMaximumExceeded         MessageErrorCode = "maximum_exceeded"
	MessageErrorCodeMinimumNotMet           MessageErrorCode = "minimum_not_met"
	MessageErrorCodeMissing                 MessageErrorCode = "missing"
	MessageErrorCodeNotFound                MessageErrorCode = "not_found"
	MessageErrorCodeOutOfStock              MessageErrorCode = "out_of_stock"
	MessageErrorCodePaymentDeclined         MessageErrorCode = "payment_declined"
	MessageErrorCodeQuantityExceeded        MessageErrorCode = "quantity_exceeded"
	MessageErrorCodeRateLimited             MessageErrorCode = "rate_limited"
	MessageErrorCodeRegionRestricted        MessageErrorCode = "region_restricted"
	MessageErrorCodeRequires3ds             MessageErrorCode = "requires_3ds"
	MessageErrorCodeRequiresSignIn          MessageErrorCode = "requires_sign_in"
	MessageErrorCodeUnsupported             MessageErrorCode = "unsupported"
)

Defines values for MessageErrorCode.

func (MessageErrorCode) Valid 

func (e MessageErrorCode) Valid() bool

Valid indicates whether the value is a known member of the MessageErrorCode enum.

type MessageErrorContentType 

type MessageErrorContentType string

MessageErrorContentType Format of the error message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting. 

const (
	MessageErrorContentTypeMarkdown MessageErrorContentType = "markdown"
	MessageErrorContentTypePlain    MessageErrorContentType = "plain"
)

Defines values for MessageErrorContentType.

func (MessageErrorContentType) Valid 

func (e MessageErrorContentType) Valid() bool

Valid indicates whether the value is a known member of the MessageErrorContentType enum.

type MessageErrorResolution 

type MessageErrorResolution string

MessageErrorResolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize. 

const (
	MessageErrorResolutionRecoverable         MessageErrorResolution = "recoverable"
	MessageErrorResolutionRequiresBuyerInput  MessageErrorResolution = "requires_buyer_input"
	MessageErrorResolutionRequiresBuyerReview MessageErrorResolution = "requires_buyer_review"
)

Defines values for MessageErrorResolution.

func (MessageErrorResolution) Valid 

func (e MessageErrorResolution) Valid() bool

Valid indicates whether the value is a known member of the MessageErrorResolution enum.

type MessageErrorSeverity 

type MessageErrorSeverity string

MessageErrorSeverity Severity level of this error 

const (
	MessageErrorSeverityCritical MessageErrorSeverity = "critical"
	MessageErrorSeverityHigh     MessageErrorSeverity = "high"
	MessageErrorSeverityInfo     MessageErrorSeverity = "info"
	MessageErrorSeverityLow      MessageErrorSeverity = "low"
	MessageErrorSeverityMedium   MessageErrorSeverity = "medium"
)

Defines values for MessageErrorSeverity.

func (MessageErrorSeverity) Valid 

func (e MessageErrorSeverity) Valid() bool

Valid indicates whether the value is a known member of the MessageErrorSeverity enum.

type MessageErrorType 

type MessageErrorType string

MessageErrorType Message type discriminator 

const (
	MessageErrorTypeError MessageErrorType = "error"
)

Defines values for MessageErrorType.

func (MessageErrorType) Valid 

func (e MessageErrorType) Valid() bool

Valid indicates whether the value is a known member of the MessageErrorType enum.

type MessageInfo 

type MessageInfo struct {
	// Content Informational message text. When content_type is 'markdown', this MUST be valid CommonMark with no raw HTML. Agents MUST render using a CommonMark-compliant parser with raw HTML output disabled or sanitized.
	Content string `json:"content"`

	// ContentType Format of the message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting.
	ContentType MessageInfoContentType `json:"content_type"`

	// Param RFC 9535 JSONPath
	Param *string `json:"param,omitempty"`

	// Resolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize.
	Resolution *MessageInfoResolution `json:"resolution,omitempty"`

	// Severity Severity level of this informational message
	Severity *MessageInfoSeverity `json:"severity,omitempty"`

	// Type Message type discriminator
	Type MessageInfoType `json:"type"`
}

MessageInfo Informational message to display to the buyer during checkout

type MessageInfoContentType 

type MessageInfoContentType string

MessageInfoContentType Format of the message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting. 

const (
	MessageInfoContentTypeMarkdown MessageInfoContentType = "markdown"
	MessageInfoContentTypePlain    MessageInfoContentType = "plain"
)

Defines values for MessageInfoContentType.

func (MessageInfoContentType) Valid 

func (e MessageInfoContentType) Valid() bool

Valid indicates whether the value is a known member of the MessageInfoContentType enum.

type MessageInfoResolution 

type MessageInfoResolution string

MessageInfoResolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize. 

const (
	MessageInfoResolutionRecoverable         MessageInfoResolution = "recoverable"
	MessageInfoResolutionRequiresBuyerInput  MessageInfoResolution = "requires_buyer_input"
	MessageInfoResolutionRequiresBuyerReview MessageInfoResolution = "requires_buyer_review"
)

Defines values for MessageInfoResolution.

func (MessageInfoResolution) Valid 

func (e MessageInfoResolution) Valid() bool

Valid indicates whether the value is a known member of the MessageInfoResolution enum.

type MessageInfoSeverity 

type MessageInfoSeverity string

MessageInfoSeverity Severity level of this informational message 

const (
	MessageInfoSeverityCritical MessageInfoSeverity = "critical"
	MessageInfoSeverityHigh     MessageInfoSeverity = "high"
	MessageInfoSeverityInfo     MessageInfoSeverity = "info"
	MessageInfoSeverityLow      MessageInfoSeverity = "low"
	MessageInfoSeverityMedium   MessageInfoSeverity = "medium"
)

Defines values for MessageInfoSeverity.

func (MessageInfoSeverity) Valid 

func (e MessageInfoSeverity) Valid() bool

Valid indicates whether the value is a known member of the MessageInfoSeverity enum.

type MessageInfoType 

type MessageInfoType string

MessageInfoType Message type discriminator 

const (
	MessageInfoTypeInfo MessageInfoType = "info"
)

Defines values for MessageInfoType.

func (MessageInfoType) Valid 

func (e MessageInfoType) Valid() bool

Valid indicates whether the value is a known member of the MessageInfoType enum.

type MessageWarning 

type MessageWarning struct {
	// Code Warning code indicating the type of warning
	Code MessageWarningCode `json:"code"`

	// Content Warning message text. When content_type is 'markdown', this MUST be valid CommonMark with no raw HTML. Agents MUST render using a CommonMark-compliant parser with raw HTML output disabled or sanitized.
	Content string `json:"content"`

	// ContentType Format of the warning message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting.
	ContentType MessageWarningContentType `json:"content_type"`

	// Param RFC 9535 JSONPath
	Param *string `json:"param,omitempty"`

	// Resolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize.
	Resolution *MessageWarningResolution `json:"resolution,omitempty"`

	// Severity Severity level of this warning
	Severity *MessageWarningSeverity `json:"severity,omitempty"`

	// Type Message type discriminator
	Type MessageWarningType `json:"type"`
}

MessageWarning Warning message to display to the buyer during checkout (non-blocking)

type MessageWarningCode 

type MessageWarningCode string

MessageWarningCode Warning code indicating the type of warning 

const (
	MessageWarningCodeDiscountCodeAlreadyApplied        MessageWarningCode = "discount_code_already_applied"
	MessageWarningCodeDiscountCodeCombinationDisallowed MessageWarningCode = "discount_code_combination_disallowed"
	MessageWarningCodeDiscountCodeExpired               MessageWarningCode = "discount_code_expired"
	MessageWarningCodeDiscountCodeInvalid               MessageWarningCode = "discount_code_invalid"
	MessageWarningCodeDiscountCodeMinimumNotMet         MessageWarningCode = "discount_code_minimum_not_met"
	MessageWarningCodeDiscountCodeUsageLimitReached     MessageWarningCode = "discount_code_usage_limit_reached"
	MessageWarningCodeDiscountCodeUserIneligible        MessageWarningCode = "discount_code_user_ineligible"
	MessageWarningCodeDiscountCodeUserNotLoggedIn       MessageWarningCode = "discount_code_user_not_logged_in"
	MessageWarningCodeExpiringPromotion                 MessageWarningCode = "expiring_promotion"
	MessageWarningCodeHighDemand                        MessageWarningCode = "high_demand"
	MessageWarningCodeLimitedAvailability               MessageWarningCode = "limited_availability"
	MessageWarningCodeLowStock                          MessageWarningCode = "low_stock"
	MessageWarningCodePriceChange                       MessageWarningCode = "price_change"
	MessageWarningCodeShippingDelay                     MessageWarningCode = "shipping_delay"
)

Defines values for MessageWarningCode.

func (MessageWarningCode) Valid 

func (e MessageWarningCode) Valid() bool

Valid indicates whether the value is a known member of the MessageWarningCode enum.

type MessageWarningContentType 

type MessageWarningContentType string

MessageWarningContentType Format of the warning message content. When set to 'markdown', content MUST conform to CommonMark (https://spec.commonmark.org/0.31.2/). Raw HTML elements MUST NOT be included. When set to 'plain', content is plain text with no formatting. 

const (
	MessageWarningContentTypeMarkdown MessageWarningContentType = "markdown"
	MessageWarningContentTypePlain    MessageWarningContentType = "plain"
)

Defines values for MessageWarningContentType.

func (MessageWarningContentType) Valid 

func (e MessageWarningContentType) Valid() bool

Valid indicates whether the value is a known member of the MessageWarningContentType enum.

type MessageWarningResolution 

type MessageWarningResolution string

MessageWarningResolution Who resolves this message. 'recoverable': agent can fix via API. 'requires_buyer_input': buyer must provide info. 'requires_buyer_review': buyer must authorize. 

const (
	MessageWarningResolutionRecoverable         MessageWarningResolution = "recoverable"
	MessageWarningResolutionRequiresBuyerInput  MessageWarningResolution = "requires_buyer_input"
	MessageWarningResolutionRequiresBuyerReview MessageWarningResolution = "requires_buyer_review"
)

Defines values for MessageWarningResolution.

func (MessageWarningResolution) Valid 

func (e MessageWarningResolution) Valid() bool

Valid indicates whether the value is a known member of the MessageWarningResolution enum.

type MessageWarningSeverity 

type MessageWarningSeverity string

MessageWarningSeverity Severity level of this warning 

const (
	MessageWarningSeverityCritical MessageWarningSeverity = "critical"
	MessageWarningSeverityHigh     MessageWarningSeverity = "high"
	MessageWarningSeverityInfo     MessageWarningSeverity = "info"
	MessageWarningSeverityLow      MessageWarningSeverity = "low"
	MessageWarningSeverityMedium   MessageWarningSeverity = "medium"
)

Defines values for MessageWarningSeverity.

func (MessageWarningSeverity) Valid 

func (e MessageWarningSeverity) Valid() bool

Valid indicates whether the value is a known member of the MessageWarningSeverity enum.

type MessageWarningType 

type MessageWarningType string

MessageWarningType Message type discriminator 

const (
	Warning MessageWarningType = "warning"
)

Defines values for MessageWarningType.

func (MessageWarningType) Valid 

func (e MessageWarningType) Valid() bool

Valid indicates whether the value is a known member of the MessageWarningType enum.

type Option 

type Option func(*config)

Option configures a Handler.

func WithServeMux 

func WithServeMux(mux *http.ServeMux) Option

WithServeMux registers cart routes on mux instead of creating a new http.ServeMux.

type Provider 

type Provider interface {
	// CreateCart creates a cart and returns its authoritative estimated state.
	CreateCart(context.Context, CartCreateRequest) (*Cart, error)
	// GetCart returns the current cart state.
	GetCart(context.Context, string) (*Cart, error)
	// UpdateCart replaces the mutable cart state and returns the updated cart.
	UpdateCart(context.Context, string, CartUpdateRequest) (*Cart, error)
	// CancelCart removes a cart and returns its final state.
	CancelCart(context.Context, string) (*Cart, error)
}

Provider owns the seller-side cart lifecycle.

type RequestId 

type RequestId = string

RequestId defines model for RequestId.

type TaxBreakdownItem 

type TaxBreakdownItem struct {
	// Amount Tax amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
	Amount int `json:"amount"`

	// Jurisdiction Tax jurisdiction name (e.g., 'California State Tax', 'City of San Francisco')
	Jurisdiction string `json:"jurisdiction"`

	// Rate Tax rate as a decimal (e.g., 0.0875 for 8.75%)
	Rate float32 `json:"rate"`
}

TaxBreakdownItem Breakdown of tax amounts by type, jurisdiction, or rate

type TaxExemption 

type TaxExemption struct {
	// CertificateId Unique identifier for the tax exemption certificate
	CertificateId string `json:"certificate_id"`

	// CertificateType Type of tax exemption certificate
	CertificateType TaxExemptionCertificateType `json:"certificate_type"`

	// ExemptRegions List of regions where the exemption applies (e.g., state codes)
	ExemptRegions *[]string `json:"exempt_regions,omitempty"`

	// ExpiresAt RFC 3339 timestamp when the exemption certificate expires
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

TaxExemption Tax exemption information including exemption type and applicable regions

type TaxExemptionCertificateType 

type TaxExemptionCertificateType string

TaxExemptionCertificateType Type of tax exemption certificate 

const (
	ExemptOrganization TaxExemptionCertificateType = "exempt_organization"
	Government         TaxExemptionCertificateType = "government"
	Resale             TaxExemptionCertificateType = "resale"
)

Defines values for TaxExemptionCertificateType.

func (TaxExemptionCertificateType) Valid 

func (e TaxExemptionCertificateType) Valid() bool

Valid indicates whether the value is a known member of the TaxExemptionCertificateType enum.

type Total 

type Total struct {
	// Amount Amount in minor currency units (e.g. 100 cents for $1.00 or 100 for ¥100)
	Amount int `json:"amount"`

	// Breakdown Detailed breakdown for tax totals
	Breakdown *[]TaxBreakdownItem `json:"breakdown,omitempty"`

	// Description Additional descriptive text for this total
	Description *string `json:"description,omitempty"`

	// DisplayText Localized display text for this total
	DisplayText string `json:"display_text"`

	// PresentmentAmount Amount in presentment currency minor units if different from settlement currency
	PresentmentAmount *int `json:"presentment_amount,omitempty"`

	// Type Type of total line item
	Type TotalType `json:"type"`
}

Total Total amounts for the checkout including subtotal, discounts, tax, shipping, and final total

type TotalType 

type TotalType string

TotalType Type of total line item 

const (
	TotalTypeAmountRefunded  TotalType = "amount_refunded"
	TotalTypeDiscount        TotalType = "discount"
	TotalTypeFee             TotalType = "fee"
	TotalTypeFulfillment     TotalType = "fulfillment"
	TotalTypeGiftWrap        TotalType = "gift_wrap"
	TotalTypeItemsBaseAmount TotalType = "items_base_amount"
	TotalTypeItemsDiscount   TotalType = "items_discount"
	TotalTypeStoreCredit     TotalType = "store_credit"
	TotalTypeSubtotal        TotalType = "subtotal"
	TotalTypeTax             TotalType = "tax"
	TotalTypeTip             TotalType = "tip"
	TotalTypeTotal           TotalType = "total"
)

Defines values for TotalType.

func (TotalType) Valid 

func (e TotalType) Valid() bool

Valid indicates whether the value is a known member of the TotalType enum.

type Unauthorized 

type Unauthorized = Error

Unauthorized Protocol-level error returned in 4xx/5xx responses when the server cannot return a valid CheckoutSession at all (e.g. malformed request or unexpected failure). Use Error—not MessageError—when there is no valid session state to return. type semantics: invalid_request — malformed request, missing required fields, invalid JSON, or idempotency violations (codes: idempotency_key_required, idempotency_in_flight, idempotency_conflict); processing_error — unexpected server-side failure; service_unavailable — temporary unavailability.

type UpdateCartJSONRequestBody 

type UpdateCartJSONRequestBody = CartUpdateRequest

UpdateCartJSONRequestBody defines body for UpdateCart for application/json ContentType.

type UpdateCartParams 

type UpdateCartParams struct {
	// Authorization Bearer token for API authentication
	Authorization  Authorization   `json:"Authorization"`
	ContentType    ContentType     `json:"Content-Type"`
	AcceptLanguage *AcceptLanguage `json:"Accept-Language,omitempty"`

	// IdempotencyKey Idempotency key. MUST be present on all POST requests. Opaque string, max 255 characters. UUID v4 recommended.
	IdempotencyKey IdempotencyKey `json:"Idempotency-Key"`
	RequestId      *RequestId     `json:"Request-Id,omitempty"`
	APIVersion     APIVersion     `json:"API-Version"`
}

UpdateCartParams defines parameters for UpdateCart.

type VariantOption 

type VariantOption struct {
	// Name Variant attribute name (e.g., 'Size', 'Color')
	Name string `json:"name"`

	// Value Variant attribute value (e.g., 'Large', 'Blue')
	Value string `json:"value"`
}

VariantOption Represents a single variant option for a product (e.g., size, color, material)

type WeightInfo 

type WeightInfo struct {
	// Unit Unit of measurement for weight
	Unit WeightInfoUnit `json:"unit"`

	// Value Numeric weight value
	Value float32 `json:"value"`
}

WeightInfo Product weight with unit of measurement

type WeightInfoUnit 

type WeightInfoUnit string

WeightInfoUnit Unit of measurement for weight 

const (
	G  WeightInfoUnit = "g"
	Kg WeightInfoUnit = "kg"
	Lb WeightInfoUnit = "lb"
	Oz WeightInfoUnit = "oz"
)

Defines values for WeightInfoUnit.

func (WeightInfoUnit) Valid 

func (e WeightInfoUnit) Valid() bool

Valid indicates whether the value is a known member of the WeightInfoUnit enum.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.