brainerce 2.7.0 → 2.8.0

package/README.md

@@ -1322,6 +1322,21 @@ The SDK uses **server-side carts for all users**. Guests get automatic session c
 > `publishProductToSalesChannel()`. Note `publishProduct()` is a DIFFERENT
 > operation — that one pushes to external platforms, not to your storefront.
 
+> **A shopper cart holds at most 50 distinct lines.** Adding a 51st _different_
+> product throws `400 "A cart can hold at most 50 different items. Remove
+> something before adding more."` It is a fixed platform limit with no per-store
+> setting. **It applies in channel (`salesChannelId: 'vc_*'`) and store
+> (`storeId`) mode only — an admin (`apiKey: 'brainerce_*'`) cart is not
+> capped**, because a B2B or bulk-import cart legitimately runs long, so the same
+> call can succeed for one client and fail for another. The cap counts distinct
+> lines, not quantity, and is only checked when a **new** line would be created,
+> so a full cart can still have quantities changed and items removed rather than
+> becoming unusable. Show it as a "your cart is full" state and keep the item the
+> shopper tried to add on screen. ⛔ Bundle and order-bump adds are **not
+> transactional**: a bundle whose lines would cross 50 throws part-way and leaves
+> the earlier products of that bundle in the cart, so re-read the cart after a
+> failed bundle add.
+
 ```typescript
 // Add to cart (guest or logged-in — same code!)
 await client.smartAddToCart({ productId: 'prod_123', quantity: 2 });
@@ -2610,6 +2625,11 @@ await client.smartAddToCart({
 > guest or a logged-in shopper, so you never need a `cartId` of your own.
 > Validation stays server-side, so a bad modifier set still comes back as a
 > `MODIFIER_VALIDATION_FAILED` envelope on `BrainerceError.details`.
+>
+> **The 50-distinct-line cap applies here too** (channel and store mode; not
+> admin). A 51st different product throws `400 "A cart can hold at most 50
+> different items. Remove something before adding more."` — see
+> [Cart (Unified for All Users)](#cart-unified-for-all-users) above.
 
 #### Get Cart
 
@@ -2874,6 +2894,12 @@ const cart = await client.addToCart(cartId, {
 });
 ```
 
+> **Capped at 50 distinct lines** in channel and store mode (not admin): a 51st
+> different product throws `400 "A cart can hold at most 50 different items.
+> Remove something before adding more."` Quantity changes on an already-full cart
+> still work — only a new line is refused. See
+> [Cart (Unified for All Users)](#cart-unified-for-all-users).
+
 #### Update Cart Item
 
 ```typescript
@@ -5994,6 +6020,55 @@ await client.setMetafieldPlatforms('def_id', {
 });
 ```
 
+### Order custom fields
+
+Merchant-defined fields that hold a value **on an order**. Not the ones a
+shopper fills in at checkout — these are the store's own, and they are how you
+attach something that only exists after the purchase: a licence key, a booking
+reference, a warranty number issued by a third party.
+
+The point of writing here rather than emailing the customer yourself: the value
+travels to the merchant's own order email templates as `orderCustomFields`, and
+shows on the customer's own order page when the definition is `isPublic`. You do
+not build an email, and the merchant keeps their branding and their language.
+
+⛔ **The stock templates do not print it.** The variable reaches every order
+email, but no default template renders it, so a value you write is invisible to
+the customer until the merchant adds the block to the template once (the email
+editor's variable helper offers `orderCustomFields`). Writing the field is not
+the same as the customer being told. Say so when you hand this to a merchant.
+
+The merchant creates the definitions in the dashboard (Orders → settings). The
+SDK reads them and writes values.
+
+```typescript
+// 1. Discover the keys. `key` is what you write; `type` is what a value must fit.
+const definitions = await client.getOrderCustomFieldDefinitions();
+
+// 2. Write. A MERGE — omitted keys keep their value, null clears a non-required one.
+const stored = await client.setOrderCustomFieldValues(
+  'order_123',
+  { licence_key: 'ABCD-EFGH-IJKL' },
+  { idempotencyKey: 'licence-order_123' }
+);
+console.log(stored.fields); // what was ACTUALLY persisted, after coercion
+
+// 3. Read back later
+const { fields } = await client.getOrderCustomFieldValues('order_123');
+```
+
+Three behaviours worth knowing before you rely on them:
+
+- **A key with no active definition is ignored, not rejected.** The call still
+  succeeds. Check the returned `fields` to confirm your value landed, rather
+  than assuming a 200 means it did.
+- **Values are coerced to the definition type.** A `NUMBER` field written as
+  `'5'` reads back as `5`. A value that cannot be coerced is a 400.
+- **`required` fields cannot be cleared.** Sending `null` for one is a 400.
+
+Requires an API key with `orders:read` (the two reads) and `orders:write` (the
+write).
+
 ### Per-Channel Publishing (Categories / Tags / Brands / Custom Fields)
 
 Each of these entities can be **gated per vibe-coded site**: merchants
@@ -8099,6 +8174,53 @@ was missing 14 real events and still listed 8 fake ones — `coupon.*`,
 subscribable events. If you're on an older SDK version, upgrade rather than
 casting around the type.)
 
+### Finishing a purchase that depends on something outside Brainerce
+
+The common shape: the customer pays, then a third party has to issue the thing
+they bought — a licence key, a booking reference, a ticket number — and only
+then can the customer be told what it is. That answer usually arrives seconds
+after payment, sometimes minutes, and occasionally never.
+
+Do not hold the order confirmation waiting for it. The confirmation is the
+receipt for the payment; send it immediately, and deliver the answer in a
+second email once you have it.
+
+```typescript
+// order.paid handler, on YOUR server
+const key = await someProvider.issue({
+  // Use the order id as the provider's idempotency reference, never a random
+  // one. A retried handler then collides with the original instead of buying
+  // a second key.
+  reference: order.id,
+});
+
+await client.setOrderCustomFieldValues(
+  order.id,
+  { licence_key: key },
+  { idempotencyKey: `licence-${order.id}` }
+);
+
+// Fires ORDER_COMPLETED, which renders the field the line above just wrote.
+await client.updateOrder(order.id, { status: 'COMPLETED' });
+```
+
+Two things this gets you for free:
+
+- **The failure case has a queue.** If the provider errors, you never mark the
+  order complete, so no email goes out claiming something was delivered. The
+  merchant's list of paid-but-not-completed orders is the list of purchases
+  needing attention, with no extra screen to build.
+- **The merchant owns the email.** The value renders through their existing
+  `ORDER_COMPLETED` template, in their branding and their language. Add the
+  field to that template once (as `orderCustomFields`) and every future
+  integration reuses it.
+
+⛔ **Marking an order `COMPLETED` also commits its inventory reservation, and
+tells the customer the whole order is done.** That is correct for a purely
+digital order. If the same order also ships a physical item, use a different
+signal — do not tell someone their parcel is finished because a licence
+arrived.
+
 ---
 
 ## TypeScript Support
@@ -8138,6 +8260,8 @@ import type {
   Order,
   OrderStatus,
   OrderItem,
+  OrderCustomFieldDefinition,
+  OrderCustomFieldValues,
 
   // Webhooks
   WebhookEvent,

package/dist/index.d.mts

@@ -2381,6 +2381,66 @@ interface CreateOrderDto {
 interface UpdateOrderDto {
     status?: OrderStatus;
 }
+/**
+ * A merchant-defined field that can hold a value on an order.
+ *
+ * These are the fields the STORE manages on an order (`adminFieldValues`), not
+ * the ones a shopper fills in during checkout. They are how an integration
+ * attaches data that only exists after the purchase — a licence key, a booking
+ * reference, a warranty number issued by a third party — to the order it
+ * belongs to. What is written travels to the merchant's own order email
+ * templates as `orderCustomFields`, so the customer can be told without a
+ * bespoke email being built for each integration.
+ *
+ * ⛔ No default template PRINTS it. The merchant adds the block to their
+ * template once; until then a written value is invisible to the customer.
+ */
+interface OrderCustomFieldDefinition {
+    id: string;
+    storeId: string;
+    /** Display label. Renders beside the value in order emails. */
+    name: string;
+    /** The property name to use in `setOrderCustomFieldValues`. */
+    key: string;
+    description: string | null;
+    type: 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE' | 'DATETIME' | 'IMAGE';
+    /** A required field cannot be cleared once it holds a value. */
+    required: boolean;
+    /**
+     * When true the value is exposed to the storefront through the SDK, so the
+     * customer can see it on their own order page and not only in the email.
+     */
+    isPublic: boolean;
+    position: number;
+    /**
+     * An inactive definition refuses new values but still resolves its label on
+     * orders that already carry one.
+     */
+    isActive: boolean;
+    /** SELECT only. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    minLength?: number | null;
+    maxLength?: number | null;
+    minValue?: string | null;
+    maxValue?: string | null;
+    dateAvailability?: unknown;
+    translations?: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The custom field values stored on one order, keyed by definition `key`. */
+interface OrderCustomFieldValues {
+    orderId: string;
+    /**
+     * Values AFTER coercion to each field's type — a NUMBER field written as
+     * `'5'` reads back as `5`. Keys with no matching definition were never
+     * stored and so never appear here.
+     */
+    fields: Record<string, unknown>;
+}
 interface UpdateInventoryDto {
     quantity: number;
     variantId?: string;
@@ -9121,6 +9181,63 @@ declare class BrainerceClient {
      * Update an order (e.g., change status)
      */
     updateOrder(orderId: string, data: UpdateOrderDto): Promise<Order>;
+    /**
+     * List the store's order custom field definitions.
+     *
+     * Call this before writing values: the `key` of each definition is what
+     * {@link setOrderCustomFieldValues} accepts, and `type` is what a value has
+     * to fit. Inactive definitions are included, so you can tell "the merchant
+     * turned this field off" apart from "the merchant never created it".
+     *
+     * Requires an API key with the `orders:read` scope.
+     */
+    getOrderCustomFieldDefinitions(): Promise<OrderCustomFieldDefinition[]>;
+    /**
+     * Read the custom field values stored on one order.
+     *
+     * Requires an API key with the `orders:read` scope.
+     */
+    getOrderCustomFieldValues(orderId: string): Promise<OrderCustomFieldValues>;
+    /**
+     * Write custom field values onto an order.
+     *
+     * This is how work that finishes OUTSIDE Brainerce gets back onto the order
+     * it belongs to. Subscribe to the `order.paid` webhook, call whatever third
+     * party issues the thing you sell — a licence key, a booking reference, a
+     * warranty number — then write the answer here. The value travels to the
+     * merchant's own order email templates as `orderCustomFields` and, when the
+     * definition is `isPublic`, to the customer's own order page. No email
+     * template or endpoint has to be built per integration.
+     *
+     * ⛔ No default template PRINTS `orderCustomFields`. The variable reaches
+     * every order email, but until the merchant adds the block to their template
+     * once, a value written here is invisible to the customer. Writing the field
+     * is not the same as the customer being told.
+     *
+     * The write is a MERGE: keys you leave out keep their current value, and
+     * `null` clears a field that is not required. Values are coerced to the
+     * definition's type and rejected with a 400 when they cannot be — but a key
+     * with no active definition on the store is IGNORED rather than failing the
+     * whole call, so read the returned `fields` to confirm what was stored.
+     *
+     * Pass an `idempotencyKey` when the caller may retry: an identical re-send
+     * then replays the original response instead of writing again.
+     *
+     * Requires an API key with the `orders:write` scope.
+     *
+     * @example
+     * ```typescript
+     * // after the third party answered
+     * await client.setOrderCustomFieldValues(
+     *   order.id,
+     *   { licence_key: 'ABCD-EFGH-IJKL' },
+     *   { idempotencyKey: `licence-${order.id}` }
+     * );
+     * // fires the "order completed" email, which carries the field
+     * await client.updateOrder(order.id, { status: 'COMPLETED' });
+     * ```
+     */
+    setOrderCustomFieldValues(orderId: string, fields: Record<string, unknown>, options?: IdempotentRequestOptions): Promise<OrderCustomFieldValues>;
     /**
      * Update order status.
      *
@@ -14186,7 +14303,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "2.7.0";
+declare const SDK_VERSION = "2.8.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -14687,4 +14804,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CheckoutTender, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type ModifierValidationFailedError, type MyProductReview, type NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CheckoutTender, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type ModifierValidationFailedError, type MyProductReview, type NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.d.ts

@@ -2381,6 +2381,66 @@ interface CreateOrderDto {
 interface UpdateOrderDto {
     status?: OrderStatus;
 }
+/**
+ * A merchant-defined field that can hold a value on an order.
+ *
+ * These are the fields the STORE manages on an order (`adminFieldValues`), not
+ * the ones a shopper fills in during checkout. They are how an integration
+ * attaches data that only exists after the purchase — a licence key, a booking
+ * reference, a warranty number issued by a third party — to the order it
+ * belongs to. What is written travels to the merchant's own order email
+ * templates as `orderCustomFields`, so the customer can be told without a
+ * bespoke email being built for each integration.
+ *
+ * ⛔ No default template PRINTS it. The merchant adds the block to their
+ * template once; until then a written value is invisible to the customer.
+ */
+interface OrderCustomFieldDefinition {
+    id: string;
+    storeId: string;
+    /** Display label. Renders beside the value in order emails. */
+    name: string;
+    /** The property name to use in `setOrderCustomFieldValues`. */
+    key: string;
+    description: string | null;
+    type: 'TEXT' | 'TEXTAREA' | 'NUMBER' | 'BOOLEAN' | 'SELECT' | 'DATE' | 'DATETIME' | 'IMAGE';
+    /** A required field cannot be cleared once it holds a value. */
+    required: boolean;
+    /**
+     * When true the value is exposed to the storefront through the SDK, so the
+     * customer can see it on their own order page and not only in the email.
+     */
+    isPublic: boolean;
+    position: number;
+    /**
+     * An inactive definition refuses new values but still resolves its label on
+     * orders that already carry one.
+     */
+    isActive: boolean;
+    /** SELECT only. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }> | null;
+    minLength?: number | null;
+    maxLength?: number | null;
+    minValue?: string | null;
+    maxValue?: string | null;
+    dateAvailability?: unknown;
+    translations?: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The custom field values stored on one order, keyed by definition `key`. */
+interface OrderCustomFieldValues {
+    orderId: string;
+    /**
+     * Values AFTER coercion to each field's type — a NUMBER field written as
+     * `'5'` reads back as `5`. Keys with no matching definition were never
+     * stored and so never appear here.
+     */
+    fields: Record<string, unknown>;
+}
 interface UpdateInventoryDto {
     quantity: number;
     variantId?: string;
@@ -9121,6 +9181,63 @@ declare class BrainerceClient {
      * Update an order (e.g., change status)
      */
     updateOrder(orderId: string, data: UpdateOrderDto): Promise<Order>;
+    /**
+     * List the store's order custom field definitions.
+     *
+     * Call this before writing values: the `key` of each definition is what
+     * {@link setOrderCustomFieldValues} accepts, and `type` is what a value has
+     * to fit. Inactive definitions are included, so you can tell "the merchant
+     * turned this field off" apart from "the merchant never created it".
+     *
+     * Requires an API key with the `orders:read` scope.
+     */
+    getOrderCustomFieldDefinitions(): Promise<OrderCustomFieldDefinition[]>;
+    /**
+     * Read the custom field values stored on one order.
+     *
+     * Requires an API key with the `orders:read` scope.
+     */
+    getOrderCustomFieldValues(orderId: string): Promise<OrderCustomFieldValues>;
+    /**
+     * Write custom field values onto an order.
+     *
+     * This is how work that finishes OUTSIDE Brainerce gets back onto the order
+     * it belongs to. Subscribe to the `order.paid` webhook, call whatever third
+     * party issues the thing you sell — a licence key, a booking reference, a
+     * warranty number — then write the answer here. The value travels to the
+     * merchant's own order email templates as `orderCustomFields` and, when the
+     * definition is `isPublic`, to the customer's own order page. No email
+     * template or endpoint has to be built per integration.
+     *
+     * ⛔ No default template PRINTS `orderCustomFields`. The variable reaches
+     * every order email, but until the merchant adds the block to their template
+     * once, a value written here is invisible to the customer. Writing the field
+     * is not the same as the customer being told.
+     *
+     * The write is a MERGE: keys you leave out keep their current value, and
+     * `null` clears a field that is not required. Values are coerced to the
+     * definition's type and rejected with a 400 when they cannot be — but a key
+     * with no active definition on the store is IGNORED rather than failing the
+     * whole call, so read the returned `fields` to confirm what was stored.
+     *
+     * Pass an `idempotencyKey` when the caller may retry: an identical re-send
+     * then replays the original response instead of writing again.
+     *
+     * Requires an API key with the `orders:write` scope.
+     *
+     * @example
+     * ```typescript
+     * // after the third party answered
+     * await client.setOrderCustomFieldValues(
+     *   order.id,
+     *   { licence_key: 'ABCD-EFGH-IJKL' },
+     *   { idempotencyKey: `licence-${order.id}` }
+     * );
+     * // fires the "order completed" email, which carries the field
+     * await client.updateOrder(order.id, { status: 'COMPLETED' });
+     * ```
+     */
+    setOrderCustomFieldValues(orderId: string, fields: Record<string, unknown>, options?: IdempotentRequestOptions): Promise<OrderCustomFieldValues>;
     /**
      * Update order status.
      *
@@ -14186,7 +14303,7 @@ declare class BrainerceError extends Error {
     constructor(message: string, statusCode: number, details?: unknown);
 }
 
-declare const SDK_VERSION = "2.7.0";
+declare const SDK_VERSION = "2.8.0";
 
 /**
  * Verify a webhook signature from Brainerce
@@ -14687,4 +14804,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CheckoutTender, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type ModifierValidationFailedError, type MyProductReview, type NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AiTranslateBulkInput, type AiTranslateBulkResult, type AiTranslateSingleInput, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AssignTaxClassDto, type AttachModifierGroupInput, type Attribute, type AttributeDisplayType, type AttributeOption, type AttributeSource, type AutoRegionResponse, type AvailabilityClock, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundleOfferOfferedProduct, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartItemUnavailableReason, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CheckoutTender, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateRegionDto, type CreateReturnLabelDto as CreateReturnLabelInput, type CreateReturnLabelResponse, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateStockAlertInput, type CreateTagDto as CreateTagInput, type CreateTaxClassDto, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type CustomizationFieldOption, type DateAvailabilityConstraints, type DateAvailabilitySurface, type DateFieldParseResult, type DeleteProductResponse, type DeliveryType, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GiftCardAdmin, type GiftCardAdminDetail, type GiftCardBalance, type GiftCardLiability, type GiftCardTransaction, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type I18nSettings, type IdempotentRequestOptions, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type IssueGiftCardAdminDto, type IssuedGiftCardAdmin, type JsonLdOptions, type ListModifierGroupsParams, type ListNewsletterBenefitGrantsParams, type LocalCart, type LocalCartItem, type LocaleTranslation, type LockedVariant, type LoyaltyBadge, type LoyaltyMembershipPlan, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyRewardRecommendation, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type ModifierValidationFailedError, type MyProductReview, type NestedModifierSelection, type NewsletterBenefitDiscountKind, type NewsletterBenefitGrant, type NewsletterBenefitGrantState, type NewsletterBenefitSettings, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthErrorCode, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomFieldDefinition, type OrderCustomFieldValues, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type PaidMembershipInfo, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentRecordStatus, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type PriceDriftError, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductInventoryResponse, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductReviewImage, type ProductReviewImageAdmin, type ProductSitemapOptions, type ProductStatus, type ProductSuggestion, type ProductUnavailableError, type ProductVariant, type PublicMetafieldDefinition, type PublicNewsletterBenefitOffer, type PublicRegion, type PublicRegionDetail, type PublicRegionPaymentProvider, type PublicTaxClass, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type Region, type RegionPaymentProvider, type RegisterCustomerDto, type ReissuedGiftCardAdmin, type RelativeDateBounds, type ResendNewsletterBenefitResult, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type ReturnLabelParcel, type ReviewPhotoUpload, type ReviewStatus, type RichTextContent, SDK_VERSION, type SavedPaymentMethodSummary, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type SetTranslationFields, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAlertResponse, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreCapabilities, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type StorefrontSavedPaymentMethod, type SubmitProductReviewInput, type SubscribeMarketingInput, type SubscribeMarketingResponse, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxClass, type TaxEstimateResponse, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type TranslatableEntityType, type TranslationStatusEntry, type TranslationsMap, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateNewsletterBenefitSettingsInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateRegionDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxClassDto, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsellSettings, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveRelativeBounds, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -204,7 +204,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.7.0";
+var SDK_VERSION = "2.8.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -2961,6 +2961,79 @@ var _BrainerceClient = class _BrainerceClient {
   async updateOrder(orderId, data) {
     return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}`, data);
   }
+  /**
+   * List the store's order custom field definitions.
+   *
+   * Call this before writing values: the `key` of each definition is what
+   * {@link setOrderCustomFieldValues} accepts, and `type` is what a value has
+   * to fit. Inactive definitions are included, so you can tell "the merchant
+   * turned this field off" apart from "the merchant never created it".
+   *
+   * Requires an API key with the `orders:read` scope.
+   */
+  async getOrderCustomFieldDefinitions() {
+    return this.adminRequest("GET", "/api/v1/order-custom-fields");
+  }
+  /**
+   * Read the custom field values stored on one order.
+   *
+   * Requires an API key with the `orders:read` scope.
+   */
+  async getOrderCustomFieldValues(orderId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/orders/${encodePathSegment(orderId)}/custom-fields`
+    );
+  }
+  /**
+   * Write custom field values onto an order.
+   *
+   * This is how work that finishes OUTSIDE Brainerce gets back onto the order
+   * it belongs to. Subscribe to the `order.paid` webhook, call whatever third
+   * party issues the thing you sell — a licence key, a booking reference, a
+   * warranty number — then write the answer here. The value travels to the
+   * merchant's own order email templates as `orderCustomFields` and, when the
+   * definition is `isPublic`, to the customer's own order page. No email
+   * template or endpoint has to be built per integration.
+   *
+   * ⛔ No default template PRINTS `orderCustomFields`. The variable reaches
+   * every order email, but until the merchant adds the block to their template
+   * once, a value written here is invisible to the customer. Writing the field
+   * is not the same as the customer being told.
+   *
+   * The write is a MERGE: keys you leave out keep their current value, and
+   * `null` clears a field that is not required. Values are coerced to the
+   * definition's type and rejected with a 400 when they cannot be — but a key
+   * with no active definition on the store is IGNORED rather than failing the
+   * whole call, so read the returned `fields` to confirm what was stored.
+   *
+   * Pass an `idempotencyKey` when the caller may retry: an identical re-send
+   * then replays the original response instead of writing again.
+   *
+   * Requires an API key with the `orders:write` scope.
+   *
+   * @example
+   * ```typescript
+   * // after the third party answered
+   * await client.setOrderCustomFieldValues(
+   *   order.id,
+   *   { licence_key: 'ABCD-EFGH-IJKL' },
+   *   { idempotencyKey: `licence-${order.id}` }
+   * );
+   * // fires the "order completed" email, which carries the field
+   * await client.updateOrder(order.id, { status: 'COMPLETED' });
+   * ```
+   */
+  async setOrderCustomFieldValues(orderId, fields, options) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/orders/${encodePathSegment(orderId)}/custom-fields`,
+      { fields },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
   /**
    * Update order status.
    *
@@ -11267,6 +11340,13 @@ var ALLOWED_PAYMENT_HOSTS = [
   // reachable, so a terminal configured against it keeps working.
   "pay.hyp.co.il",
   "icom.yaad.net",
+  // iCredit (ריווחית) — the hosted payment page returned by
+  // PaymentPageRequest. Both environments are listed EXPLICITLY rather than
+  // allowing `rivhit.co.il`: the matcher below also accepts `*.<host>`, so a
+  // bare parent entry would open every Rivhit subdomain (their accounting app,
+  // marketing site, anything they add later) to a payment redirect.
+  "icredit.rivhit.co.il",
+  "testicredit.rivhit.co.il",
   // Brainerce-hosted payment embeds (backend payment-embed proxy at
   // `/api/payment/embed/...` that fronts provider apps' embed shells —
   // e.g. cardcom-payments OpenFields wrapper). The match also covers

package/dist/index.mjs

@@ -115,7 +115,7 @@ function isDevGuardsEnabled() {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.7.0";
+var SDK_VERSION = "2.8.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.brainerce.com";
@@ -2872,6 +2872,79 @@ var _BrainerceClient = class _BrainerceClient {
   async updateOrder(orderId, data) {
     return this.request("PATCH", `/api/v1/orders/${encodePathSegment(orderId)}`, data);
   }
+  /**
+   * List the store's order custom field definitions.
+   *
+   * Call this before writing values: the `key` of each definition is what
+   * {@link setOrderCustomFieldValues} accepts, and `type` is what a value has
+   * to fit. Inactive definitions are included, so you can tell "the merchant
+   * turned this field off" apart from "the merchant never created it".
+   *
+   * Requires an API key with the `orders:read` scope.
+   */
+  async getOrderCustomFieldDefinitions() {
+    return this.adminRequest("GET", "/api/v1/order-custom-fields");
+  }
+  /**
+   * Read the custom field values stored on one order.
+   *
+   * Requires an API key with the `orders:read` scope.
+   */
+  async getOrderCustomFieldValues(orderId) {
+    return this.adminRequest(
+      "GET",
+      `/api/v1/orders/${encodePathSegment(orderId)}/custom-fields`
+    );
+  }
+  /**
+   * Write custom field values onto an order.
+   *
+   * This is how work that finishes OUTSIDE Brainerce gets back onto the order
+   * it belongs to. Subscribe to the `order.paid` webhook, call whatever third
+   * party issues the thing you sell — a licence key, a booking reference, a
+   * warranty number — then write the answer here. The value travels to the
+   * merchant's own order email templates as `orderCustomFields` and, when the
+   * definition is `isPublic`, to the customer's own order page. No email
+   * template or endpoint has to be built per integration.
+   *
+   * ⛔ No default template PRINTS `orderCustomFields`. The variable reaches
+   * every order email, but until the merchant adds the block to their template
+   * once, a value written here is invisible to the customer. Writing the field
+   * is not the same as the customer being told.
+   *
+   * The write is a MERGE: keys you leave out keep their current value, and
+   * `null` clears a field that is not required. Values are coerced to the
+   * definition's type and rejected with a 400 when they cannot be — but a key
+   * with no active definition on the store is IGNORED rather than failing the
+   * whole call, so read the returned `fields` to confirm what was stored.
+   *
+   * Pass an `idempotencyKey` when the caller may retry: an identical re-send
+   * then replays the original response instead of writing again.
+   *
+   * Requires an API key with the `orders:write` scope.
+   *
+   * @example
+   * ```typescript
+   * // after the third party answered
+   * await client.setOrderCustomFieldValues(
+   *   order.id,
+   *   { licence_key: 'ABCD-EFGH-IJKL' },
+   *   { idempotencyKey: `licence-${order.id}` }
+   * );
+   * // fires the "order completed" email, which carries the field
+   * await client.updateOrder(order.id, { status: 'COMPLETED' });
+   * ```
+   */
+  async setOrderCustomFieldValues(orderId, fields, options) {
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/orders/${encodePathSegment(orderId)}/custom-fields`,
+      { fields },
+      void 0,
+      "json",
+      this.idempotencyHeaders(options)
+    );
+  }
   /**
    * Update order status.
    *
@@ -11178,6 +11251,13 @@ var ALLOWED_PAYMENT_HOSTS = [
   // reachable, so a terminal configured against it keeps working.
   "pay.hyp.co.il",
   "icom.yaad.net",
+  // iCredit (ריווחית) — the hosted payment page returned by
+  // PaymentPageRequest. Both environments are listed EXPLICITLY rather than
+  // allowing `rivhit.co.il`: the matcher below also accepts `*.<host>`, so a
+  // bare parent entry would open every Rivhit subdomain (their accounting app,
+  // marketing site, anything they add later) to a payment redirect.
+  "icredit.rivhit.co.il",
+  "testicredit.rivhit.co.il",
   // Brainerce-hosted payment embeds (backend payment-embed proxy at
   // `/api/payment/embed/...` that fronts provider apps' embed shells —
   // e.g. cardcom-payments OpenFields wrapper). The match also covers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",