From 77246d5715d8d48183a4ea067c50eafb92939850 Mon Sep 17 00:00:00 2001 From: Michael Woodward Date: Wed, 10 Jul 2024 14:13:05 +0100 Subject: [PATCH] feat: Align SDK with API (#15) - Adds Product to Subscription items - Improves documentation of types --- CHANGELOG.md | 5 ++- adjustments.go | 13 +++---- customers.go | 6 ++-- discounts.go | 18 +++++----- notification_settings.go | 6 ++-- pkg/paddlenotification/adjustments.go | 34 ++++++++---------- pkg/paddlenotification/customers.go | 6 ++-- pkg/paddlenotification/discounts.go | 10 +++--- pkg/paddlenotification/shared.go | 33 +++++++++++++++--- pkg/paddlenotification/subscriptions.go | 2 ++ pkg/paddlenotification/transactions.go | 26 -------------- prices.go | 11 +++--- pricing_preview.go | 4 +-- products.go | 2 +- shared.go | 46 +++++++++++-------------- subscriptions.go | 9 +++-- transactions.go | 8 ++--- 17 files changed, 118 insertions(+), 121 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c0b9ec8..f176786 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,11 @@ Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx ### Breaking changes -- Paddle API enum types are now correctly enforced where applicable +- Paddle API enum types are now correctly enforced where applicable +### Added + +- `Product` has been added as a property of `SubscriptionItem` ## 0.4.0 - 2024-06-26 diff --git a/adjustments.go b/adjustments.go index 508f4ec..8d45edb 100644 --- a/adjustments.go +++ b/adjustments.go @@ -195,16 +195,17 @@ func (c *AdjustmentsClient) ListAdjustments(ctx context.Context, req *ListAdjust // CreateAdjustmentRequest is given as an input to CreateAdjustment. type CreateAdjustmentRequest struct { - // Action: How this adjustment impacts the related transaction. `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval`. + // Action: How this adjustment impacts the related transaction. Action Action `json:"action,omitempty"` - // Items: List of items on this adjustment. + // Items: List of transaction items to adjust. Items []AdjustmentItem `json:"items,omitempty"` - // Reason: Why this adjustment was created. Appears in the Paddle Dashboard. Retained for record-keeping purposes. + // Reason: Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes. Reason string `json:"reason,omitempty"` /* - TransactionID: Paddle ID for the transaction related to this adjustment, prefixed with `txn_`. - Transactions must be `billed` or `completed`. You can't create an adjustment for a transaction - that has an adjustment that's `pending_approval`. + TransactionID: Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`. + Transactions must be manually-collected, and have a status of `billed` or `completed`. + + You can't create an adjustment for a transaction that has a refund that's pending approval. */ TransactionID string `json:"transaction_id,omitempty"` } diff --git a/customers.go b/customers.go index df70d63..3a7023f 100644 --- a/customers.go +++ b/customers.go @@ -38,8 +38,8 @@ type Customer struct { // Email: Email address for this customer. Email string `json:"email,omitempty"` /* - MarketingConsent: Whether this customer opted into marketing from you. - Set to `true` by Paddle where a customer checks the marketing consent box when using Paddle Checkout; `false` otherwise. + MarketingConsent: Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box + when using Paddle Checkout. Set automatically by Paddle. */ MarketingConsent bool `json:"marketing_consent,omitempty"` // Status: Whether this entity can be used in Paddle. @@ -152,7 +152,7 @@ type UpdateCustomerRequest struct { Status *PatchField[Status] `json:"status,omitempty"` // CustomData: Your own structured key-value data. CustomData *PatchField[CustomData] `json:"custom_data,omitempty"` - // Locale: Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`. + // Locale: Valid IETF BCP 47 short form locale tag. Locale *PatchField[string] `json:"locale,omitempty"` } diff --git a/discounts.go b/discounts.go index 86a6cc0..ea6364e 100644 --- a/discounts.go +++ b/discounts.go @@ -100,15 +100,15 @@ type CreateDiscountRequest struct { Amount string `json:"amount,omitempty"` // Description: Short description for this discount for your reference. Not shown to customers. Description string `json:"description,omitempty"` - // Type: Type of discount. + // Type: Type of discount. Determines how this discount impacts the transaction total. Type DiscountType `json:"type,omitempty"` - // EnabledForCheckout: Whether this discount can be applied by a customer at checkout. + // EnabledForCheckout: Whether this discount can be applied by customers at checkout. If omitted, defaults to `false`. EnabledForCheckout *bool `json:"enabled_for_checkout,omitempty"` - // Code: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. Paddle generates a random 10-character code if a code is not provided and `enabled_for_checkout` is `true`. + // Code: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. If omitted and `enabled_for_checkout` is `true`, Paddle generates a random 10-character code. Code *string `json:"code,omitempty"` // CurrencyCode: Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`. CurrencyCode *CurrencyCode `json:"currency_code,omitempty"` - // Recur: Whether this discount applies for multiple billing periods. + // Recur: Whether this discount applies for multiple subscription billing periods. If omitted, defaults to `false`. Recur *bool `json:"recur,omitempty"` // MaximumRecurringIntervals: Amount of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. MaximumRecurringIntervals *int `json:"maximum_recurring_intervals,omitempty"` @@ -116,7 +116,7 @@ type CreateDiscountRequest struct { UsageLimit *int `json:"usage_limit,omitempty"` // RestrictTo: Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices. RestrictTo []string `json:"restrict_to,omitempty"` - // ExpiresAt: RFC 3339 datetime string of when this discount expires. Discount can no longer be applied after this date has elapsed. `null` if this discount can be applied forever. + // ExpiresAt: RFC 3339 datetime string of when this discount expires. Discount can no longer be applied after this date has elapsed. `null` if this discount can be applied forever. If omitted, defaults to `null`. ExpiresAt *string `json:"expires_at,omitempty"` // CustomData: Your own structured key-value data. CustomData CustomData `json:"custom_data,omitempty"` @@ -155,17 +155,17 @@ type UpdateDiscountRequest struct { Status *PatchField[DiscountStatus] `json:"status,omitempty"` // Description: Short description for this discount for your reference. Not shown to customers. Description *PatchField[string] `json:"description,omitempty"` - // EnabledForCheckout: Whether this discount can be applied by a customer at checkout. + // EnabledForCheckout: Whether this discount can be applied by customers at checkout. EnabledForCheckout *PatchField[bool] `json:"enabled_for_checkout,omitempty"` - // Code: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. Paddle generates a random 10-character code if a code is not provided and `enabled_for_checkout` is `true`. + // Code: Unique code that customers can use to apply this discount at checkout. Code *PatchField[*string] `json:"code,omitempty"` - // Type: Type of discount. + // Type: Type of discount. Determines how this discount impacts the transaction total. Type *PatchField[DiscountType] `json:"type,omitempty"` // Amount: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. Amount *PatchField[string] `json:"amount,omitempty"` // CurrencyCode: Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`. CurrencyCode *PatchField[*CurrencyCode] `json:"currency_code,omitempty"` - // Recur: Whether this discount applies for multiple billing periods. + // Recur: Whether this discount applies for multiple subscription billing periods. Recur *PatchField[bool] `json:"recur,omitempty"` // MaximumRecurringIntervals: Amount of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. MaximumRecurringIntervals *PatchField[*int] `json:"maximum_recurring_intervals,omitempty"` diff --git a/notification_settings.go b/notification_settings.go index d915a4b..66a8b2b 100644 --- a/notification_settings.go +++ b/notification_settings.go @@ -24,7 +24,7 @@ type NotificationSetting struct { Destination string `json:"destination,omitempty"` // Active: Whether Paddle should try to deliver events to this notification destination. Active bool `json:"active,omitempty"` - // APIVersion: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Cannot be a version older than your account default. Defaults to your account default if not included. + // APIVersion: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Cannot be a version older than your account default. APIVersion int `json:"api_version,omitempty"` // IncludeSensitiveFields: Whether potentially sensitive fields should be sent to this notification destination. IncludeSensitiveFields bool `json:"include_sensitive_fields,omitempty"` @@ -79,9 +79,9 @@ type CreateNotificationSettingRequest struct { SubscribedEvents []Event `json:"subscribed_events,omitempty"` // Type: Where notifications should be sent for this destination. Type NotificationSettingType `json:"type,omitempty"` - // APIVersion: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Cannot be a version older than your account default. Defaults to your account default if not included. + // APIVersion: API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Cannot be a version older than your account default. If omitted, defaults to your account default version. APIVersion *int `json:"api_version,omitempty"` - // IncludeSensitiveFields: Whether potentially sensitive fields should be sent to this notification destination. + // IncludeSensitiveFields: Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to `false`. IncludeSensitiveFields *bool `json:"include_sensitive_fields,omitempty"` } diff --git a/pkg/paddlenotification/adjustments.go b/pkg/paddlenotification/adjustments.go index e19f81f..a1cd188 100644 --- a/pkg/paddlenotification/adjustments.go +++ b/pkg/paddlenotification/adjustments.go @@ -16,7 +16,7 @@ type AdjustmentUpdated struct { Data AdjustmentNotification `json:"data"` } -// Action: How this adjustment impacts the related transaction. `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval`.. +// Action: How this adjustment impacts the related transaction.. type Action string const ( @@ -31,9 +31,9 @@ const ( /* AdjustmentStatus: Status of this adjustment. Set automatically by Paddle. -`refund` adjustments must be approved by Paddle, and are created with the status `pending_approval` -until they move to `approved` or `rejected` on review. Other kinds of adjustment do not need approval, -so are created with the status `approved`.. +Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes. + +Credit adjustments don't require approval from Paddle, so they're created as `approved`.. */ type AdjustmentStatus string @@ -45,7 +45,7 @@ const ( ) /* -AdjustmentType: Type of adjustment for this transaction item. `tax` and `proration` are automatically created by Paddle. +AdjustmentType: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment.. */ type AdjustmentType string @@ -74,16 +74,13 @@ type AdjustmentItem struct { // ItemID: Paddle ID for the transaction item that this adjustment item relates to, prefixed with `txnitm_`. ItemID string `json:"item_id,omitempty"` /* - Type: Type of adjustment for this transaction item. `tax` and `proration` are automatically created by Paddle. + Type: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment. */ Type AdjustmentType `json:"type,omitempty"` // Amount: Amount adjusted for this transaction item. Required when adjustment type is `partial`. Amount *string `json:"amount,omitempty"` - /* - Proration: How proration was calculated for this adjustment item. Populated when an adjustment type is `proration`. - Set automatically by Paddle. - */ + // Proration: How proration was calculated for this adjustment item. Proration *Proration `json:"proration,omitempty"` // Totals: Breakdown of the total for an adjustment item. Totals AdjustmentItemTotals `json:"totals,omitempty"` @@ -132,9 +129,9 @@ type PayoutTotalsAdjustment struct { type AdjustmentNotification struct { // ID: Unique Paddle ID for this adjustment entity, prefixed with `adj_`. ID string `json:"id,omitempty"` - // Action: How this adjustment impacts the related transaction. `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval`. + // Action: How this adjustment impacts the related transaction. Action Action `json:"action,omitempty"` - // TransactionID: Paddle ID for the transaction related to this adjustment, prefixed with `txn_`. + // TransactionID: Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`. TransactionID string `json:"transaction_id,omitempty"` /* SubscriptionID: Paddle ID for the subscription related to this adjustment, prefixed with `sub_`. @@ -146,15 +143,14 @@ type AdjustmentNotification struct { Set automatically by Paddle based on the `customer_id` of the related transaction. */ CustomerID string `json:"customer_id,omitempty"` - // Reason: Why this adjustment was created. Appears in the Paddle Dashboard. Retained for record-keeping purposes. + // Reason: Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes. Reason string `json:"reason,omitempty"` /* CreditAppliedToBalance: Whether this adjustment was applied to the related customer's credit balance. Only returned for `credit` adjustments. - `false` when the related transaction `collection_mode` is `manual` and its `status` is `billed`. The adjustment is used - to reduce the `balance` due on the transaction. + `false` where the related transaction is `billed`. The adjustment reduces the amount due on the transaction. - `true` for automatically-collected transactions and `completed` manually-collected transactions. + `true` where the related transaction is `completed`. The amount is added the customer's credit balance and used to pay future transactions. */ CreditAppliedToBalance *bool `json:"credit_applied_to_balance,omitempty"` // CurrencyCode: Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the `currency_code` of the related transaction. @@ -162,9 +158,9 @@ type AdjustmentNotification struct { /* Status: Status of this adjustment. Set automatically by Paddle. - `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval` - until they move to `approved` or `rejected` on review. Other kinds of adjustment do not need approval, - so are created with the status `approved`. + Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes. + + Credit adjustments don't require approval from Paddle, so they're created as `approved`. */ Status AdjustmentStatus `json:"status,omitempty"` // Items: List of items on this adjustment. diff --git a/pkg/paddlenotification/customers.go b/pkg/paddlenotification/customers.go index 0ad9418..88e262e 100644 --- a/pkg/paddlenotification/customers.go +++ b/pkg/paddlenotification/customers.go @@ -32,15 +32,15 @@ type CustomerNotification struct { // Email: Email address for this customer. Email string `json:"email,omitempty"` /* - MarketingConsent: Whether this customer opted into marketing from you. - Set to `true` by Paddle where a customer checks the marketing consent box when using Paddle Checkout; `false` otherwise. + MarketingConsent: Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box + when using Paddle Checkout. Set automatically by Paddle. */ MarketingConsent bool `json:"marketing_consent,omitempty"` // Status: Whether this entity can be used in Paddle. Status Status `json:"status,omitempty"` // CustomData: Your own structured key-value data. CustomData CustomData `json:"custom_data,omitempty"` - // Locale: Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`. + // Locale: Valid IETF BCP 47 short form locale tag. Locale string `json:"locale,omitempty"` // CreatedAt: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. CreatedAt string `json:"created_at,omitempty"` diff --git a/pkg/paddlenotification/discounts.go b/pkg/paddlenotification/discounts.go index 8c6df7a..bd37e15 100644 --- a/pkg/paddlenotification/discounts.go +++ b/pkg/paddlenotification/discounts.go @@ -33,7 +33,7 @@ const ( DiscountStatusUsed DiscountStatus = "used" ) -// Type: Type of discount.. +// Type: Type of discount. Determines how this discount impacts the transaction total.. type Type string const ( @@ -50,17 +50,17 @@ type DiscountNotification struct { Status DiscountStatus `json:"status,omitempty"` // Description: Short description for this discount for your reference. Not shown to customers. Description string `json:"description,omitempty"` - // EnabledForCheckout: Whether this discount can be applied by a customer at checkout. + // EnabledForCheckout: Whether this discount can be applied by customers at checkout. EnabledForCheckout bool `json:"enabled_for_checkout,omitempty"` - // Code: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. Paddle generates a random 10-character code if a code is not provided and `enabled_for_checkout` is `true`. + // Code: Unique code that customers can use to apply this discount at checkout. Code *string `json:"code,omitempty"` - // Type: Type of discount. + // Type: Type of discount. Determines how this discount impacts the transaction total. Type Type `json:"type,omitempty"` // Amount: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. Amount string `json:"amount,omitempty"` // CurrencyCode: Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`. CurrencyCode *CurrencyCode `json:"currency_code,omitempty"` - // Recur: Whether this discount applies for multiple billing periods. + // Recur: Whether this discount applies for multiple subscription billing periods. Recur bool `json:"recur,omitempty"` // MaximumRecurringIntervals: Amount of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. MaximumRecurringIntervals *int `json:"maximum_recurring_intervals,omitempty"` diff --git a/pkg/paddlenotification/shared.go b/pkg/paddlenotification/shared.go index d9dafbb..218ba75 100644 --- a/pkg/paddlenotification/shared.go +++ b/pkg/paddlenotification/shared.go @@ -297,10 +297,7 @@ type TimePeriod struct { EndsAt string `json:"ends_at,omitempty"` } -/* -Proration: How proration was calculated for this adjustment item. Populated when an adjustment type is `proration`. -Set automatically by Paddle. -*/ +// Proration: How proration was calculated for this adjustment item. type Proration struct { // Rate: Rate used to calculate proration. Rate string `json:"rate,omitempty"` @@ -438,7 +435,7 @@ const ( // BillingDetails: Details for invoicing. Required if `collection_mode` is `manual`. type BillingDetails struct { - // EnableCheckout: Whether the related transaction may be paid using a Paddle Checkout. + // EnableCheckout: Whether the related transaction may be paid using a Paddle Checkout. If omitted when creating a transaction, defaults to `false`. EnableCheckout bool `json:"enable_checkout,omitempty"` // PurchaseOrderNumber: Customer purchase order number. Appears on invoice documents. PurchaseOrderNumber string `json:"purchase_order_number,omitempty"` @@ -483,4 +480,30 @@ type Price struct { // UpdatedAt: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. UpdatedAt string `json:"updated_at,omitempty"` } + +// Product: Related product entity for this item. This reflects the product entity at the time it was added to the subscription. +type Product struct { + // ID: Unique Paddle ID for this product, prefixed with `pro_`. + ID string `json:"id,omitempty"` + // Name: Name of this product. + Name string `json:"name,omitempty"` + // Description: Short description for this product. + Description *string `json:"description,omitempty"` + // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. + Type CatalogType `json:"type,omitempty"` + // TaxCategory: Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account. + TaxCategory TaxCategory `json:"tax_category,omitempty"` + // ImageURL: Image for this product. Included in the checkout and on some customer documents. + ImageURL *string `json:"image_url,omitempty"` + // CustomData: Your own structured key-value data. + CustomData CustomData `json:"custom_data,omitempty"` + // Status: Whether this entity can be used in Paddle. + Status Status `json:"status,omitempty"` + // ImportMeta: Import information for this entity. `null` if this entity is not imported. + ImportMeta *ImportMeta `json:"import_meta,omitempty"` + // CreatedAt: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. + CreatedAt string `json:"created_at,omitempty"` + // UpdatedAt: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. + UpdatedAt string `json:"updated_at,omitempty"` +} type CustomData map[string]any diff --git a/pkg/paddlenotification/subscriptions.go b/pkg/paddlenotification/subscriptions.go index da03a65..fffa824 100644 --- a/pkg/paddlenotification/subscriptions.go +++ b/pkg/paddlenotification/subscriptions.go @@ -134,6 +134,8 @@ type SubscriptionItem struct { TrialDates *TimePeriod `json:"trial_dates,omitempty"` // Price: Related price entity for this item. This reflects the price entity at the time it was added to the subscription. Price Price `json:"price,omitempty"` + // Product: Related product entity for this item. This reflects the product entity at the time it was added to the subscription. + Product Product `json:"product,omitempty"` } // SubscriptionNotification: New or changed entity. diff --git a/pkg/paddlenotification/transactions.go b/pkg/paddlenotification/transactions.go index f57483e..02846f7 100644 --- a/pkg/paddlenotification/transactions.go +++ b/pkg/paddlenotification/transactions.go @@ -239,32 +239,6 @@ type UnitTotals struct { Total string `json:"total,omitempty"` } -// Product: Related product entity for this transaction line item price. -type Product struct { - // ID: Unique Paddle ID for this product, prefixed with `pro_`. - ID string `json:"id,omitempty"` - // Name: Name of this product. - Name string `json:"name,omitempty"` - // Description: Short description for this product. - Description *string `json:"description,omitempty"` - // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. - Type CatalogType `json:"type,omitempty"` - // TaxCategory: Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account. - TaxCategory TaxCategory `json:"tax_category,omitempty"` - // ImageURL: Image for this product. Included in the checkout and on some customer documents. - ImageURL *string `json:"image_url,omitempty"` - // CustomData: Your own structured key-value data. - CustomData CustomData `json:"custom_data,omitempty"` - // Status: Whether this entity can be used in Paddle. - Status Status `json:"status,omitempty"` - // ImportMeta: Import information for this entity. `null` if this entity is not imported. - ImportMeta *ImportMeta `json:"import_meta,omitempty"` - // CreatedAt: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle. - CreatedAt string `json:"created_at,omitempty"` - // UpdatedAt: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle. - UpdatedAt string `json:"updated_at,omitempty"` -} - // TransactionLineItem: Information about line items for this transaction. Different from transaction `items` as they include totals calculated by Paddle. Considered the source of truth for line item totals. type TransactionLineItem struct { // ID: Unique Paddle ID for this transaction item, prefixed with `txnitm_`. diff --git a/prices.go b/prices.go index e35468a..674d852 100644 --- a/prices.go +++ b/prices.go @@ -143,15 +143,18 @@ type CreatePriceRequest struct { ProductID string `json:"product_id,omitempty"` // UnitPrice: Base price. This price applies to all customers, except for customers located in countries where you have `unit_price_overrides`. UnitPrice Money `json:"unit_price,omitempty"` - // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. + // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. If omitted, defaults to `standard`. Type *CatalogType `json:"type,omitempty"` // Name: Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills. Name *string `json:"name,omitempty"` - // BillingCycle: How often this price should be charged. `null` if price is non-recurring (one-time). + // BillingCycle: How often this price should be charged. `null` if price is non-recurring (one-time). If omitted, defaults to `null`. BillingCycle *Duration `json:"billing_cycle,omitempty"` - // TrialPeriod: Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billing_cycle`. + /* + TrialPeriod: Trial period for the product related to this price. The billing cycle begins once the trial period is over. + `null` for no trial period. Requires `billing_cycle`. If omitted, defaults to `null`. + */ TrialPeriod *Duration `json:"trial_period,omitempty"` - // TaxMode: How tax is calculated for this price. + // TaxMode: How tax is calculated for this price. If omitted, defaults to `account_setting`. TaxMode *TaxMode `json:"tax_mode,omitempty"` // UnitPriceOverrides: List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries. UnitPriceOverrides []UnitPriceOverride `json:"unit_price_overrides,omitempty"` diff --git a/pricing_preview.go b/pricing_preview.go index 815d4cd..4191798 100644 --- a/pricing_preview.go +++ b/pricing_preview.go @@ -111,6 +111,8 @@ type PricingPreviewClient struct { // PricePreviewRequest is given as an input to PricePreview. type PricePreviewRequest struct { + // Items: List of items to preview price calculations for. + Items []PricePreviewItem `json:"items,omitempty"` // CustomerID: Paddle ID of the customer that this preview is for, prefixed with `ctm_`. CustomerID *string `json:"customer_id,omitempty"` // AddressID: Paddle ID of the address that this preview is for, prefixed with `add_`. Send one of `address_id`, `customer_ip_address`, or the `address` object when previewing. @@ -125,8 +127,6 @@ type PricePreviewRequest struct { Address *AddressPreview `json:"address,omitempty"` // CustomerIPAddress: IP address for this transaction preview. Send one of `address_id`, `customer_ip_address`, or the `address` object when previewing. CustomerIPAddress *string `json:"customer_ip_address,omitempty"` - // Items: List of items to preview price calculations for. - Items []PricePreviewItem `json:"items,omitempty"` } // PricePreview performs the POST operation on a Pricing preview resource. diff --git a/products.go b/products.go index 2f12410..a7e2ffa 100644 --- a/products.go +++ b/products.go @@ -102,7 +102,7 @@ type CreateProductRequest struct { TaxCategory TaxCategory `json:"tax_category,omitempty"` // Description: Short description for this product. Description *string `json:"description,omitempty"` - // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. + // Type: Type of item. Standard items are considered part of your catalog and are shown on the Paddle web app. If omitted, defaults to `standard`. Type *CatalogType `json:"type,omitempty"` // ImageURL: Image for this product. Included in the checkout and on some customer documents. ImageURL *string `json:"image_url,omitempty"` diff --git a/shared.go b/shared.go index 3b604ca..7624fd1 100644 --- a/shared.go +++ b/shared.go @@ -580,7 +580,7 @@ const ( // BillingDetails: Details for invoicing. Required if `collection_mode` is `manual`. type BillingDetails struct { - // EnableCheckout: Whether the related transaction may be paid using a Paddle Checkout. + // EnableCheckout: Whether the related transaction may be paid using a Paddle Checkout. If omitted when creating a transaction, defaults to `false`. EnableCheckout bool `json:"enable_checkout,omitempty"` // PurchaseOrderNumber: Customer purchase order number. Appears on invoice documents. PurchaseOrderNumber string `json:"purchase_order_number,omitempty"` @@ -991,7 +991,7 @@ type Address struct { ImportMeta *ImportMeta `json:"import_meta,omitempty"` } -// Action: How this adjustment impacts the related transaction. `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval`.. +// Action: How this adjustment impacts the related transaction.. type Action string const ( @@ -1006,9 +1006,9 @@ const ( /* AdjustmentStatus: Status of this adjustment. Set automatically by Paddle. -`refund` adjustments must be approved by Paddle, and are created with the status `pending_approval` -until they move to `approved` or `rejected` on review. Other kinds of adjustment do not need approval, -so are created with the status `approved`.. +Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes. + +Credit adjustments don't require approval from Paddle, so they're created as `approved`.. */ type AdjustmentStatus string @@ -1020,7 +1020,7 @@ const ( ) /* -AdjustmentType: Type of adjustment for this transaction item. `tax` and `proration` are automatically created by Paddle. +AdjustmentType: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment.. */ type AdjustmentType string @@ -1049,16 +1049,13 @@ type AdjustmentItem struct { // ItemID: Paddle ID for the transaction item that this adjustment item relates to, prefixed with `txnitm_`. ItemID string `json:"item_id,omitempty"` /* - Type: Type of adjustment for this transaction item. `tax` and `proration` are automatically created by Paddle. + Type: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment. */ Type AdjustmentType `json:"type,omitempty"` // Amount: Amount adjusted for this transaction item. Required when adjustment type is `partial`. Amount *string `json:"amount,omitempty"` - /* - Proration: How proration was calculated for this adjustment item. Populated when an adjustment type is `proration`. - Set automatically by Paddle. - */ + // Proration: How proration was calculated for this adjustment item. Proration *Proration `json:"proration,omitempty"` // Totals: Breakdown of the total for an adjustment item. Totals AdjustmentItemTotals `json:"totals,omitempty"` @@ -1107,9 +1104,9 @@ type PayoutTotalsAdjustment struct { type Adjustment struct { // ID: Unique Paddle ID for this adjustment entity, prefixed with `adj_`. ID string `json:"id,omitempty"` - // Action: How this adjustment impacts the related transaction. `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval`. + // Action: How this adjustment impacts the related transaction. Action Action `json:"action,omitempty"` - // TransactionID: Paddle ID for the transaction related to this adjustment, prefixed with `txn_`. + // TransactionID: Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`. TransactionID string `json:"transaction_id,omitempty"` /* SubscriptionID: Paddle ID for the subscription related to this adjustment, prefixed with `sub_`. @@ -1121,15 +1118,14 @@ type Adjustment struct { Set automatically by Paddle based on the `customer_id` of the related transaction. */ CustomerID string `json:"customer_id,omitempty"` - // Reason: Why this adjustment was created. Appears in the Paddle Dashboard. Retained for record-keeping purposes. + // Reason: Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes. Reason string `json:"reason,omitempty"` /* CreditAppliedToBalance: Whether this adjustment was applied to the related customer's credit balance. Only returned for `credit` adjustments. - `false` when the related transaction `collection_mode` is `manual` and its `status` is `billed`. The adjustment is used - to reduce the `balance` due on the transaction. + `false` where the related transaction is `billed`. The adjustment reduces the amount due on the transaction. - `true` for automatically-collected transactions and `completed` manually-collected transactions. + `true` where the related transaction is `completed`. The amount is added the customer's credit balance and used to pay future transactions. */ CreditAppliedToBalance *bool `json:"credit_applied_to_balance,omitempty"` // CurrencyCode: Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the `currency_code` of the related transaction. @@ -1137,9 +1133,9 @@ type Adjustment struct { /* Status: Status of this adjustment. Set automatically by Paddle. - `refund` adjustments must be approved by Paddle, and are created with the status `pending_approval` - until they move to `approved` or `rejected` on review. Other kinds of adjustment do not need approval, - so are created with the status `approved`. + Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes. + + Credit adjustments don't require approval from Paddle, so they're created as `approved`. */ Status AdjustmentStatus `json:"status,omitempty"` // Items: List of items on this adjustment. @@ -1198,7 +1194,7 @@ const ( DiscountStatusUsed DiscountStatus = "used" ) -// DiscountType: Type of discount.. +// DiscountType: Type of discount. Determines how this discount impacts the transaction total.. type DiscountType string const ( @@ -1215,17 +1211,17 @@ type Discount struct { Status DiscountStatus `json:"status,omitempty"` // Description: Short description for this discount for your reference. Not shown to customers. Description string `json:"description,omitempty"` - // EnabledForCheckout: Whether this discount can be applied by a customer at checkout. + // EnabledForCheckout: Whether this discount can be applied by customers at checkout. EnabledForCheckout bool `json:"enabled_for_checkout,omitempty"` - // Code: Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 16 characters. Paddle generates a random 10-character code if a code is not provided and `enabled_for_checkout` is `true`. + // Code: Unique code that customers can use to apply this discount at checkout. Code *string `json:"code,omitempty"` - // Type: Type of discount. + // Type: Type of discount. Determines how this discount impacts the transaction total. Type DiscountType `json:"type,omitempty"` // Amount: Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency. Amount string `json:"amount,omitempty"` // CurrencyCode: Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`. CurrencyCode *CurrencyCode `json:"currency_code,omitempty"` - // Recur: Whether this discount applies for multiple billing periods. + // Recur: Whether this discount applies for multiple subscription billing periods. Recur bool `json:"recur,omitempty"` // MaximumRecurringIntervals: Amount of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever. MaximumRecurringIntervals *int `json:"maximum_recurring_intervals,omitempty"` diff --git a/subscriptions.go b/subscriptions.go index ec88ce7..598113f 100644 --- a/subscriptions.go +++ b/subscriptions.go @@ -436,6 +436,8 @@ type SubscriptionItem struct { TrialDates *TimePeriod `json:"trial_dates,omitempty"` // Price: Related price entity for this item. This reflects the price entity at the time it was added to the subscription. Price Price `json:"price,omitempty"` + // Product: Related product entity for this item. This reflects the product entity at the time it was added to the subscription. + Product Product `json:"product,omitempty"` } // SubscriptionsTaxRatesUsed: List of tax rates applied to this transaction preview. @@ -479,16 +481,13 @@ type SubscriptionsAdjustmentItem struct { // ItemID: Paddle ID for the transaction item that this adjustment item relates to, prefixed with `txnitm_`. ItemID string `json:"item_id,omitempty"` /* - Type: Type of adjustment for this transaction item. `tax` and `proration` are automatically created by Paddle. + Type: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment. */ Type AdjustmentType `json:"type,omitempty"` // Amount: Amount adjusted for this transaction item. Required when adjustment type is `partial`. Amount *string `json:"amount,omitempty"` - /* - Proration: How proration was calculated for this adjustment item. Populated when an adjustment type is `proration`. - Set automatically by Paddle. - */ + // Proration: How proration was calculated for this adjustment item. Proration *Proration `json:"proration,omitempty"` // Totals: Breakdown of the total for an adjustment item. Totals AdjustmentItemTotals `json:"totals,omitempty"` diff --git a/transactions.go b/transactions.go index b3cef3d..08f26c1 100644 --- a/transactions.go +++ b/transactions.go @@ -928,17 +928,17 @@ type CreateTransactionRequest struct { transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled. */ Status *TransactionStatus `json:"status,omitempty"` - // CustomerID: Paddle ID of the customer that this transaction is for, prefixed with `ctm_`. + // CustomerID: Paddle ID of the customer that this transaction is for, prefixed with `ctm_`. If omitted, transaction status is `draft`. CustomerID *string `json:"customer_id,omitempty"` - // AddressID: Paddle ID of the address that this transaction is for, prefixed with `add_`. + // AddressID: Paddle ID of the address that this transaction is for, prefixed with `add_`. Requires `customer_id`. If omitted, transaction status is `draft`. AddressID *string `json:"address_id,omitempty"` - // BusinessID: Paddle ID of the business that this transaction is for, prefixed with `biz_`. + // BusinessID: Paddle ID of the business that this transaction is for, prefixed with `biz_`. Requires `customer_id`. BusinessID *string `json:"business_id,omitempty"` // CustomData: Your own structured key-value data. CustomData CustomData `json:"custom_data,omitempty"` // CurrencyCode: Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`. CurrencyCode *CurrencyCode `json:"currency_code,omitempty"` - // CollectionMode: How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices. + // CollectionMode: How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices. If omitted, defaults to `automatic`. CollectionMode *CollectionMode `json:"collection_mode,omitempty"` // DiscountID: Paddle ID of the discount applied to this transaction, prefixed with `dsc_`. DiscountID *string `json:"discount_id,omitempty"`