diff --git a/models/email_templates/combined/README.md b/models/email_templates/combined/README.md new file mode 100644 index 000000000..3d6690d38 --- /dev/null +++ b/models/email_templates/combined/README.md @@ -0,0 +1,32 @@ +# Email Template Objects + +Object schemas for handlebars email templates. + +## Directory structure + +```shell +. +├── data # json data for generating and updating yaml schema +├── _all.yml # Groups models together for docs +├── account_details_changed_email.yml # Individual email template models +├── ... +``` + +## Updating models + +To generate a new model from json data and overwrite the existing schema file: + +1. Copy and paste template `data-*.json` from [localization-tools](https://github.com/bigcommerce/localization-tools/blob/master/email-check/modules/email-templates/types/abandoned_cart_email/data-0.json) to `models/_json/email_templates`. +2. Use `models/json2schema.py` to convert the json data to a yaml schema. + +Example: + +```bash +cat data.json | python json2schema.py > schema.yml +``` + +Bash for overwriting all email template models: + +```bash +for f in models/email_templates/data/*.json; do cat $f | python models/json2schema.py > ${f%.*}.yml; mv ${f%.*}.yml models/email_templates/; done +``` \ No newline at end of file diff --git a/models/email_templates/combined/abandoned_cart_email.yml b/models/email_templates/combined/abandoned_cart_email.yml new file mode 100644 index 000000000..3c283fec8 --- /dev/null +++ b/models/email_templates/combined/abandoned_cart_email.yml @@ -0,0 +1,169 @@ +title: Abandoned Cart Email Template +description: Abandoned cart email triggers when a shopper doesnʼt complete an order. +type: object +properties: + notification: + type: array + items: + type: object + properties: + unsubscribe_link: + type: string + checkout_link: + type: string + coupon: + type: array + items: + type: object + properties: + code: + type: string + type: + type: array + items: + type: object + properties: + value: + type: string + formatted: + type: string + amount: + type: array + items: + type: object + properties: + value: + type: number + format: float + formatted: + type: string + cart: + type: array + items: + type: object + properties: + products: + type: array + items: + type: object + properties: + type: array + items: + type: object + properties: + id: + type: number + url: + type: string + name: + type: string + quantity: + type: integer + sku: + type: string + thumbnail: + type: string + attributes: + type: array + items: + type: object + properties: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + price: + type: array + items: + type: object + properties: + value: + type: number + format: float + formatted: + type: string + type: + type: array + items: + type: object + properties: + value: + type: integer + formatted: + type: string + store: + type: array + items: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: array + items: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + path: + type: string + address: + type: string + phone_number: + type: string + language: + type: array + items: + type: object + properties: + code: + type: string + direction: + type: string + customer: + type: array + items: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + id: + type: number + name: + type: string + misc: + type: array + items: + type: object + properties: + year: + type: integer diff --git a/models/email_templates/combined/abandoned_cart_email_deprecated.yml b/models/email_templates/combined/abandoned_cart_email_deprecated.yml new file mode 100644 index 000000000..1cd67fbd6 --- /dev/null +++ b/models/email_templates/combined/abandoned_cart_email_deprecated.yml @@ -0,0 +1,119 @@ +title: Abandoned Cart Email Template (Deprecated) +description: Abandoned cart email triggers when a shopper doesnʼt complete an order. +type: object +deprecated: true +properties: + abandoned_cart: + type: object + title: deprecated + deprecated: true + properties: + body: + type: string + unsubscribe_link: + type: string + store: + type: object + deprecated: true + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + deprecated: true + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + deprecated: true + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + deprecated: true + properties: + year: + type: integer + translations: + type: object + deprecated: true + properties: + en: + type: object + properties: + unsubscribe: + type: string +examples: + Abandoned Cart example (deprecated): + value: + abandoned_cart: + body: You recently visited our online store and we noticed that you didnʼt complete your order.\n
To complete your order right now, just click on the link below:\n Complete your order + unsubscribe_link: 'example.com/unsubscribe' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + unsubscribe: 'Unsubscribe from future emails like this.' diff --git a/models/email_templates/combined/account_details_changed_email.yml b/models/email_templates/combined/account_details_changed_email.yml new file mode 100644 index 000000000..2bce30060 --- /dev/null +++ b/models/email_templates/combined/account_details_changed_email.yml @@ -0,0 +1,128 @@ +title: Account Settings Edited Email Template +description: Account settings email triggers when the store admin or a customer edits account settings. +type: object +properties: + details_changed: + type: object + properties: + fields: + type: array + items: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + warning: + type: string + thanks: + type: string + security: + type: string + go_shopping: + type: string +example: + details_changed: + fields: + - Email + - Password + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Your {{name}} account details have changed + hello: Hello {{name}}, + message: 'We wanted to let you know that the following details have been changed on your {{name}} account:' + warning: 'If you made the changes yourself, please disregard this email. If not, please contact the store immediately through their website: {{domain}}.' + thanks: Thanks, + security: The BigCommerce Security Team + go_shopping: Go shopping diff --git a/models/email_templates/combined/account_reset_password_email.yml b/models/email_templates/combined/account_reset_password_email.yml new file mode 100644 index 000000000..5e60b6431 --- /dev/null +++ b/models/email_templates/combined/account_reset_password_email.yml @@ -0,0 +1,112 @@ +title: Password Reset Email Template +description: Password reset email triggers when a customer resets their account password on the customer details page. +type: object +properties: + reset_password: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + message: + type: string + go_shopping: + type: string +example: + reset_password: + link: #reset-password-link + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John, + full_name: John Jr, + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Change your password for {{name}} + message: 'To change your customer account password at {{store}} please click this link or copy and paste it into your browser:' + go_shopping: Go shopping diff --git a/models/email_templates/combined/combined_order_status_email.yml b/models/email_templates/combined/combined_order_status_email.yml new file mode 100644 index 000000000..bc64b12a9 --- /dev/null +++ b/models/email_templates/combined/combined_order_status_email.yml @@ -0,0 +1,260 @@ +title: Order Status Update Email Template +description: Order status update email triggers when the status of an order changes. +type: object +properties: + order: + type: object + properties: + id: + type: integer + new_status: + type: string + example: 'Incomplete, Pending, Shipped, Partially Shipped, Refunded, Cancelled, Declined, Awaiting Payment, Awaiting Pickup, Awaiting Shipment, Completed, Awaiting Fulfillment, Manual Verification Required, Disputed, Partially Refunded' + new_formatted_status: + type: string + example: 'Shipment123, PendingOrder345, Cancelled0223222, Awaiting Payment in Store' + total: + type: object + properties: + value: + type: float + formatted: + type: string + refund: + type: object + properties: + value: + type: float + formatted: + type: string + date_placed: + type: object + properties: + value: + type: integer + formatted: + type: string + payment_method: + type: string + link: + type: string + customer_name: + type: string + downloadable_products: + type: array + items: + type: object + properties: + name: + type: string + options: + type: string + quantity: + type: integer + link: + type: string + thumbnail: + type: string + products: + type: array + items: + type: object + properties: + name: + type: string + sku: + type: string + price: + type: string + quantity: + type: integer + thumbnail: + type: string + brand: + type: string + tracking: + type: array + items: + type: object + properties: + id: + type: string + shipping_method: + type: string + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + details_title: + type: string + order_total: + type: string + date_placed: + type: string + payment_method: + type: string + total_refund: + type: string + products_shipped: + type: string + products_to_be_shipped: + type: string + tracking_title: + type: string + downloadable_items_title: + type: string + quantity: + type: string + download: + type: string + tracking_label: + type: string + no_tracking_numbers: + type: string + check_status: + type: string + go_shopping: + type: string +example: + order: + id: 1 + new_status: Awaiting Fulfillment + total: + value: 10 + formatted: $10.00 USD + refund: + value: 0 + formatted: + date_placed: + value: 1614615796 + formatted: 03/01/2121 + payment_method: Store Credit + link: '#status-link' + customer_name: John Cena + downloadable_products: + name: Journal + options: + quantity: 1 + link: '#downloadable-link' + products: + name: Test product + sku: FA44 + quantity: 11 + tracking: + id: 123BC + shipping_method: DHL + link: '#example.com' + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '= My Dev Store 97434969 =' + name: 'avatar-2020_1612860757__16350.jpeg' + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2023 + translations: + en: + title: Order status changed + hello: Hi + message: 'The status of your order #id has changed to {{status}}.' + details_title: Order details + order_total: 'Order total:' + date_placed: 'Date placed:' + payment_method: 'Payment method:' + total_refund: 'Total refunded:' + products_shipped: Products shipped + products_to_be_shipped: Products to be shipped + tracking_title: Tracking information + downloadable_items_title: Downloadable items + quantity: 'Qty:' + download: Download file + tracking_label: Tracking Link + no_tracking_numbers: No tracking numbers are assigned to your order yet + check_status: Check order status + go_shopping: Go shopping + diff --git a/models/email_templates/combined/create_account_email.yml b/models/email_templates/combined/create_account_email.yml new file mode 100644 index 000000000..92cd78317 --- /dev/null +++ b/models/email_templates/combined/create_account_email.yml @@ -0,0 +1,128 @@ +title: Account Created Email Template +description: Account created email triggers when a customer or store admin creates their account. +type: object +properties: + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + details_title: + type: string + email_label: + type: string + password_label: + type: string + password_placeholder: + type: string + sign_in: + type: string + help: + type: string + go_shopping: + type: string +example: + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: john.f@example.com + misc: + year: 2021 + translations: + en: + title: Thanks for registering at {{store}} + hello: Hello {{name}}. + message: Thank you for creating your account at {{name}}. + details_title: Account details + email_label: 'Email Address:' + password_label: 'Password:' + password_placeholder: [The password you specified] + sign_in: Sign in to account + help: If you have any questions regarding your account, click 'Reply' in your email client and we'll be only too happy to help. + go_shopping: Go shopping + + diff --git a/models/email_templates/combined/create_guest_account_email.yml b/models/email_templates/combined/create_guest_account_email.yml new file mode 100644 index 000000000..486291670 --- /dev/null +++ b/models/email_templates/combined/create_guest_account_email.yml @@ -0,0 +1,114 @@ +title: Create Guest Account Email Template +description: Guest account created email triggers when a customer or store admin creates a guest account. +type: object +properties: + guest_account: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + instruction: + type: string + help: + type: string + go_shopping: + type: string +examples: + guest_account: + link: 'https://example.com/reset-password' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Welcome to {{name}} + hello: Hello {{name}}, + message: For your convenience, we've created you an account on {{store}} so you can check the status of your order and checkout quicker in the future. + instruction: 'To login you will need to follow the link below to nominate your password:' + help: If you have any questions regarding your account, click 'Reply' in your email client and we'll be only too happy to help. + go_shopping: Go shopping diff --git a/models/email_templates/combined/gift_certificate_email.yml b/models/email_templates/combined/gift_certificate_email.yml new file mode 100644 index 000000000..e77e2361f --- /dev/null +++ b/models/email_templates/combined/gift_certificate_email.yml @@ -0,0 +1,155 @@ +title: Gift Certificate Email Template +description: Gift certificate recipient email triggers when a customer purchases a gift certificate. +type: object +properties: + certificate: + type: object + properties: + code: + type: string + to_name: + type: string + to_email: + type: string + from_name: + type: string + from_email: + type: string + amount: + type: string + redeem_link: + type: string + expiry_date: + type: object + properties: + formatted: + type: string + value: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + expiry_info: + type: string + instruction: + type: string + attached: + type: string + warning: + type: string + go_shopping: + type: string +example: + certificate: + code: FA-21465 + to_name: John + to_email: 'john.f@example.com' + from_name: John Wick + from_email: 'johnwick@example.com' + amount: '12.34' + redeem_link: '#redeem-link' + expiry_date: + formatted: 03/01/2121 + value: 1614615821 + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225 USA' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: You have received a Gift Certificate for {{name}} + hello: Dear {{name}}, + message: '{{from_name}} ({{from_email}}) has sent you a {{amount}} gift certificate for {{name]}.' + expiry_info: You have until {{date}} to use this gift certificate before it expires. + instruction: 'For instructions on how to redeem your gift certificate please click here.' + attached: Your gift certificate is attached to this email. + warning: Please download or print a copy of your gift certificate for safe keeping as gift certificates are non-transferable. + go_shopping: Go shopping diff --git a/models/email_templates/combined/global.yml b/models/email_templates/combined/global.yml new file mode 100644 index 000000000..16140df2d --- /dev/null +++ b/models/email_templates/combined/global.yml @@ -0,0 +1,88 @@ +title: Global Email Template Object +description: Data objects across all email templates. +type: object +properties: + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer +example: + store: + name: string, + domain_name: string + logo: + title: string + name: string + url: string + ssl_path: string + cdn_path: string + image_directory: string + img_path: string + path_normal: string + path: string + address: string + language: + code: string + direction: string + customer: + first_name: string + full_name: string + email: string + misc: + year: int diff --git a/models/email_templates/combined/invoice_email.yml b/models/email_templates/combined/invoice_email.yml new file mode 100644 index 000000000..4c2113a9c --- /dev/null +++ b/models/email_templates/combined/invoice_email.yml @@ -0,0 +1,523 @@ +title: Order Email Template +description: Order email triggers when a customer or store admin creates an order. +type: object +properties: + order: + type: object + properties: + id: + type: integer + customer_message: + type: string + customer_id: + type: integer + date_placed: + type: object + properties: + formatted: + type: string + value: + type: integer + account_order_status_url: + type: string + shipping: + type: object + properties: + methods: + type: array + items: + type: object + properties: + address: + type: object + properties: + email: + type: string + phone: + type: string + first_name: + type: string + last_name: + type: string + company: + type: string + country: + type: string + city: + type: string + state: + type: string + zip: + type: string + address_lines: + type: array + items: + type: object + properties: + custom_fields: + type: array + items: + type: object + properties: + products: + type: array + items: + type: object + properties: + name: + type: string + quantity: + type: integer + sku: + type: string + address_lines: + type: array + items: + type: object + properties: + address_id: + type: integer + options: + type: object + properties: + Size: + type: string + download_url: + type: string + thumbnail: + type: string + brand: + type: string + event: + type: object + properties: + name: + type: string + date: + type: object + properties: + value: + type: integer + formatted: + type: string + price: + type: object + properties: + value: + type: float + formatted: + type: string + total: + type: object + properties: + value: + type: float + formatted: + type: string + preorder: + type: object + properties: + is_preorder: + type: boolean + message: + type: string + date: + type: object + properties: + value: + type: integer + formatted: + type: string + attribute_lines: + type: array + description: A list of strings that represents product variant options. + items: + type: object + properties: + configurable_fields: + type: array + description: Object array with properties name and value. + items: + type: object + properties: + payment: + type: object + properties: + is_test: + type: boolean + provider_name: + type: string + offline_payment_message: + type: string + gateway_amount: + type: object + description: Price value. Provided only if the payment method is offline. + properties: + formatted: + type: string + value: + type: float + billing: + type: object + properties: + is_managed_by_amazon: + type: boolean + address: + type: object + properties: + email: + type: string + phone: + type: string + first_name: + type: string + last_name: + type: string + company: + type: string + country: + type: string + city: + type: string + state: + type: string + zip: + type: string + address_lines: + type: array + items: + type: object + properties: + custom_fields: + type: array + items: + type: object + properties: + total_rows: + type: array + items: + type: object + properties: + label: + type: string + price: + type: object + properties: + value: + type: float + formatted: + type: string + shipping_discounts: + type: array + items: + type: object + properties: + total_cost: + type: object + properties: + formatted: + type: string + value: + type: float + meta: + type: object + properties: + mandate_url: + type: string + description: Link to the confirmation page in Stripe + mandate_tag: + type: string + description: Short name of the payment document + shipping_addresses_num: + type: integer + show_immediate_download: + type: boolean + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + comment_label: + type: string + order_id_line: + type: string + view_summary: + type: string + sepa: + type: string + description: A link to SEPA mandate and also receive this link embedded on email confirmation. + shipment_to_multiple_addresses: + type: string + shipping_immediate_download: + type: string + shipping_address_label: + type: string + immediate_download: + type: string + email: + type: string + billing_address_managed_by_amazon: + type: string + billing_address_label: + type: string + pending_payment: + type: string + how_to_pay: + type: string + pay_for_order_help: + type: string + order_total: + type: string + cart_items: + type: string + sku: + type: string + quantity: + type: string + item_price: + type: string + item_total: + type: string + payment_method: + type: string + no_payment_taken_in_test_mode: + type: string + download_files: + type: string + preorder: + type: string + download_available_after_payment: + type: string + shipped_to: + type: string + shipping_discount: + type: string + thanks_for_your_order: + type: string + your_order_contains: + type: string + shipping_method: + type: string + shipping_to_address: + type: string + your_order_will_be_shipped_by: + type: string + total_cost: + type: string + items: + type: string + total: + type: string + price: + type: string + email_address: + type: string +examples: + order: + id: 1 + customer_message: Order custom message + customer_id: 11 + date_placed: + formatted: 11th Feb 2021 + value: 1613060604 + account_order_status_url: #url + shipping: + methods: + address: + email: 'test@gmail.com' + phone: +112233445566 + first_name: John + last_name: Wick + company: MyCompany + country: + city: + state: + zip: 1622 + address_lines: + custom_fields: + products: + - name: Test product name + quantity: 2 + sku: SF42 + address_lines: + address_id: 0 + options: + Size: XL + download_url: + thumbnail_url: /test.jpg + event: + name: + date: + value: 0 + formatted: + price: + value: 250.1 + formatted: 250.1 + total: + value: 250.1, + formatted: 250.1 + preorder: + is_preorder: false + message: + date: + value: 0 + formatted: + attribute_lines: + configurable_fields: + payment: + is_test: false + provider_name: PaymentMethod + offline_payment_message: + gateway_amount: + formatted: + value: 0 + billing: + is_managed_by_amazon: false + address: + email: 'test@gmail.com' + phone: +112233445566 + first_name: John + last_name: Wick + company: MyCompany + country: + city: + state: + zip: 1622 + address_lines: + custom_fields: + total_rows: + - label: Total, + price: + value: 250.1, + formatted: 250.1 + shipping_discounts: + total_cost: + formatted: 100.0$, + value: 100 + meta: + mandate_url: + shipping_addresses_num: 1 + show_immediate_download: false + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: [= My Dev Store 97434969 =] + name: 'avatar-2020_1612860757__16350.jpeg' + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John, + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + comment_label: Order Instructions/Comments + order_id_line: Your order ID is #{{id}}. + view_summary: A summary of your order is shown below. To view the status of your order click here. + sepa: 'SEPA Direct Debit Mandate' + shipment_to_multiple_addresses: (Order will be shipped to multiple addresses) + shipping_immediate_download: Immediate download after completion of payment. + shipping_address_label: Shipping Address + immediate_download: Immediate Download + email: Email + billing_address_managed_by_amazon: Managed by Amazon + billing_address_label: Billing Address + pending_payment: Your order requires payment before it can be finalized. Details on how to pay are shown below. + how_to_pay: Your order requires payment before it can be finalized. Details on how to pay are shown below. + pay_for_order_help: Once you've provided payment your order will be completed. + order_total: The outstanding balance of your order is amount + cart_items: Cart Items + sku: SKU + quantity: Qty + item_price: Item Price + item_total: Item Total + payment_method: Payment Method + no_payment_taken_in_test_mode: 'Please Note: No money was taken for this order, because the payment provider is in test mode.' + download_files: Download Files + preorder: This product is available for pre-order only + download_available_after_payment: Items available for immediate download after completion of payment + shipped_to: Items shipped to address + shipping_discount: price off using code Coupon Code + thanks_for_your_order: Thanks for Your Order + your_order_contains: Your Order Contains... + shipping_method: Shipping Method + shipping_to_address: Shipping to Address + your_order_will_be_shipped_by: Your Order Will Be Shipped By... + total_cost: Total Cost + items: Items + total: Total + price: Price + email_address: Email Address diff --git a/models/email_templates/combined/order_message_notification.yml b/models/email_templates/combined/order_message_notification.yml new file mode 100644 index 000000000..9c9c987af --- /dev/null +++ b/models/email_templates/combined/order_message_notification.yml @@ -0,0 +1,123 @@ +title: Order Notification Email Template +description: Order notification email triggers when a retailer or store admin adds a message to an order. +type: object +properties: + notification: + type: object + properties: + message: + type: string + link: + type: string + subject: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + reply: + type: string + go_shopping: + type: string +example: + notification: + message: Message from the retailer + link: 'https://my-dev-store-97434969.store.bcdev/account.php?action=inbox' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: New Reply to your Order Message + hello: Hello {{name}}. + message: '{{name}} has sent you a message about your order.' + reply: Reply + go_shopping: Go shopping diff --git a/models/email_templates/combined/passwordless_login_email.yml b/models/email_templates/combined/passwordless_login_email.yml new file mode 100644 index 000000000..30db28ba8 --- /dev/null +++ b/models/email_templates/combined/passwordless_login_email.yml @@ -0,0 +1,120 @@ +title: Sign in Link Request Email Template +description: Sign-in request email triggers when an existing customer requests passwordless login while checking out. +type: object +properties: + passwordless_login: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + message: + type: string + alternatively: + type: string + login_request: + type: string + secure: + type: string + go_shopping: + type: string +example: + passwordless_login: '"link": "#sign-in-link"' + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Please click the link below to sign in to your account with {{name}} + message: 'You have requested a sign-in link. Please click here to sign in and continue.' + alternatively: 'Alternatively, paste the following link in your browser:' + login_request: This login is for {{name}} if you did not request this link, please ignore this email. + secure: Your account is still secure. + go_shopping: Go shopping diff --git a/models/email_templates/combined/product_review_email.yml b/models/email_templates/combined/product_review_email.yml new file mode 100644 index 000000000..ad5eea723 --- /dev/null +++ b/models/email_templates/combined/product_review_email.yml @@ -0,0 +1,143 @@ +title: Product Review Email Template +description: Product review request email triggers after a customer purchases a product. +type: object +properties: + review: + type: object + properties: + products: + type: array + items: + type: object + properties: + name: + type: string + sku: + type: string + link: + type: string + price: + type: string + thumbnail: + type: string + unsubscribe_link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + instruction: + type: string + review_text: + type: string + thanks: + type: string + go_shopping: + type: string +examples: + review: + products: + - name: Name of Product + sku: FA44 + link: '#review-link' + unsubscribe_link: '#unsubscribe-link' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Review products you've recently purchased + hello: Hello {{name}}, + message: Thanks for your recent order with us!, + instruction: If you have a few minutes, we'd like to invite you to review the products you ordered. Just click on the link below to write a review and share your opinion with other shoppers. + review_text: Review product + thanks: Thanks in advance for taking the time to review the products you purchased! + go_shopping: Go shopping diff --git a/models/email_templates/combined/return_confirmation_email.yml b/models/email_templates/combined/return_confirmation_email.yml new file mode 100644 index 000000000..108a0977b --- /dev/null +++ b/models/email_templates/combined/return_confirmation_email.yml @@ -0,0 +1,163 @@ +title: Return Requested Email Template +description: 'Return requested email triggers after a customer’s return is approved.' +type: object +properties: + return: + type: object + properties: + return_id: + type: string + reason: + type: string + action: + type: string + comments: + type: string + products: + type: array + items: + type: object + properties: + name: + type: string + quantity: + type: integer + price: + type: string + sku: + type: string + thumbnail: + type: string + order: + type: object + properties: + id: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + confirmation: + type: string + summary: + type: string + clickHere: + type: string + reason: + type: string + action: + type: string + comments: + type: string + contains: + type: string + items: + type: string + quantity: + type: string +example: + return: + return_id: 123 + reason: reason of return + action: action + comments: sample comment + order_id: 321 + products: + - name: Shower Gel + quantity: 3 + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + confirmation: Confirmation for Return Request for Order ID + summary: A summary of your return is shown below. To view the status of this return + clickHere: click here + reason: Return Reason + action: Return Action + comments: Your Comments + contains: Your Return Request Contains the Following Items... + items: Return Items + quantity: Qty diff --git a/models/email_templates/combined/return_status_change_email.yml b/models/email_templates/combined/return_status_change_email.yml new file mode 100644 index 000000000..7b712671b --- /dev/null +++ b/models/email_templates/combined/return_status_change_email.yml @@ -0,0 +1,201 @@ +description: Return status change email triggers after a customer returnʼs status has changed. +type: object +title: Return Status Change Email Template +properties: + return: + type: object + properties: + id: + type: integer + reason: + type: string + action: + type: string + comments: + type: string + product: + type: object + properties: + name: + type: string + quantity: + type: integer + price: + type: string + sku: + type: string + thumbnail: + type: string + status: + type: object + properties: + value: + type: integer + formatted: + type: string + store_credit: + type: object + properties: + value: + type: float + formatted: + type: string + link: + type: string + instructions: + type: string + order: + type: object + properties: + id: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + received_credit: + type: string + details_title: + type: string + return_reason: + type: string + return_action: + type: string + return_comments: + type: string + check_status: + type: string + products_title: + type: string + quantity: + type: string + instructions_title: + type: string + go_shopping: + type: string +example: + return: + id: 1 + reason: reason of return + action: action + comments: sample comment + product: + name: ProductName + quantity: 2 + thumbnail_url: '' + status: + value: 1 + formatted: Pending + store_credit: + value: 10.1 + formatted: '$10.1 USD' + link: 'https://my-dev-store-97434969.store.bcdev/account.php?action=view_returns' + instructions: + order: + id: 1 + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: 'Return request status changed' + hello: 'Hello {{name}}' + message: 'The status of your return request for order #{{id}} has changed to {{status}}.' + received_credit: 'You have received a store credit of {{credits}} To use it simply place your order and you will be able to choose store credit as the payment method when it comes time to pay for your order.' + details_title: Return details + return_reason: 'Return reason:' + return_action: 'Return action:' + return_comments: 'Your comments:' + check_status: Check return status + products_title: Return items + quantity: 'Qty:' + instructions_title: 'Return Instructions:' + go_shopping: Go shopping diff --git a/models/webhooks/_all.yml b/models/webhooks/_all.yml index 3b831b392..47b246ed7 100644 --- a/models/webhooks/_all.yml +++ b/models/webhooks/_all.yml @@ -180,7 +180,8 @@ properties: allOf: - $ref: ./store_customer_payment_instrument_default_updated.yml store/customer/updated: - description: Fires when a customer is updated. Does not currently track changes to the customer address. + description: Fires when a customer is updated. It does not currently track changes to the customer address.

Tracks changes to customer attributes only if you make the changes through the control panel. This change triggers the same event `type` and payload as updating a customer; the payload does not include customer attributes. + type: object allOf: - $ref: ./store_customer_updated.yml diff --git a/models/webhooks/store_customer_updated.yml b/models/webhooks/store_customer_updated.yml index 082ba88b9..8335dd95f 100644 --- a/models/webhooks/store_customer_updated.yml +++ b/models/webhooks/store_customer_updated.yml @@ -1,7 +1,12 @@ type: object properties: store/customer/updated: - description: Fires when a customer is updated. Does not currently track changes to the customer address. + description: |- + Fires when a customer is updated. It does not currently track changes to the customer address. + + + Tracks changes to customer attributes only if you make the changes through the control panel. This change triggers the same event `type` and payload as updating a customer; the payload does not include customer attributes. + type: object properties: scope: diff --git a/reference/abandoned_cart_emails.v3.yaml b/reference/abandoned_cart_emails.v3.yaml index eb8a5efc4..7674f9067 100644 --- a/reference/abandoned_cart_emails.v3.yaml +++ b/reference/abandoned_cart_emails.v3.yaml @@ -506,15 +506,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/abandoned_carts.v3.yml b/reference/abandoned_carts.v3.yml index 96fbecec9..b53d3f156 100644 --- a/reference/abandoned_carts.v3.yml +++ b/reference/abandoned_carts.v3.yml @@ -87,13 +87,6 @@ paths: operationId: getChannelAbandonedCartSettings tags: - Abandoned Carts Settings - parameters: - - name: channel_id - description: The channel ID of the settings overrides - in: path - required: true - schema: - type: integer responses: '200': description: OK @@ -120,12 +113,6 @@ paths: tags: - Abandoned Carts Settings parameters: - - name: channel_id - description: The channel ID of the settings overrides - in: path - required: true - schema: - type: integer - $ref: '#/components/parameters/ContentType' requestBody: required: true @@ -154,13 +141,13 @@ paths: $ref: '#/components/schemas/ErrorResponse' security: [] parameters: - - $ref: '#/components/parameters/Accept' - - schema: - type: string - name: channel_id + - name: channel_id + description: The channel ID of the settings overrides in: path required: true + schema: + type: integer '/abandoned-carts/{token}': get: responses: @@ -336,15 +323,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -385,7 +372,7 @@ components: properties: cart_id: type: string - description: The `cart_id` of the abandoned cart. Can be used to display the abandoned cart to the customer using storefront cart or + description: The `cart_id` of the abandoned cart. Can be used to display the abandoned cart to the customer using storefront cart or server-to-server cart APIs. x-internal: false AbandonedCartSettings: description: Represents all settings related to the abandoned cart functionality of a store diff --git a/reference/carts.sf.yml b/reference/carts.sf.yml index 0b4bfe6cd..7b0adb56f 100644 --- a/reference/carts.sf.yml +++ b/reference/carts.sf.yml @@ -5,9 +5,14 @@ info: description: |- Manage cart operations and data using frontend JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com servers: - url: 'https://{store_domain}/api/storefront' variables: @@ -66,6 +71,20 @@ paths: - optionId: 10 optionValue: Some Text Value locale: en + With Gift Wrapping: + value: + lineItems: + - quantity: 2 + productId: 230 + optionSelections: + - optionId: 10 + optionValue: Some Text Value + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" + locale: en required: true responses: '200': @@ -104,10 +123,10 @@ paths: description: |- Adds a line items to the *Cart*. - - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: addCartLineItem parameters: @@ -155,6 +174,17 @@ paths: optionValue: 117 - optionId: 11 optionValue: 125 + With Gift Wrapping: + value: + lineItems: + - quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" description: '' '/carts/{cartId}/items/{itemId}': put: @@ -164,12 +194,13 @@ paths: description: |- Updates a *Cart* line item. Updates an existing, single line item quantity and the price of custom items in a cart. - If a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the [Delete Cart Line Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoints. You can also use carts mutations that are part of the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout). + If a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the [Delete Cart Line Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoints. You can also use carts mutations that are part of the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: updateCartLineItem parameters: @@ -227,6 +258,24 @@ paths: - optionId: 125 optionValue: 127 locale: en + With Gift Wrapping: + value: + lineItem: + quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" + With null Gift Wrapping (will delete current gift wrapping): + value: + lineItem: + quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: null required: true responses: '200': @@ -504,6 +553,39 @@ components: type: string description: 'Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.' x-internal: false + requestPostOrPutGiftWrapping: + title: Gift Wrapping Request Data + required: + - wrapTogether + - wrapDetails + type: object + nullable: true + description: if passing null, it will remove the current gift wrapping for the item + properties: + wrapTogether: + type: boolean + description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually. + example: true + wrapDetails: + type: array + description: |- + Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value. + If wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. + (e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping) + If wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped + items: + type: object + required: + - id + properties: + id: + type: integer + description: Identifier of the gift wrapping option selected. + example: 0 + message: + type: string + description: Custom gift message. + example: Happy Birthday LineItemsRequest: title: requestLineItems oneOf: @@ -605,7 +687,7 @@ components: readOnly: true id: type: string - description: Id of the custom item + description: ID of the custom item readOnly: true example: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff listPrice: @@ -919,6 +1001,8 @@ components: quantity: type: number description: Quantity of this item. + giftWrapping: + $ref: '#/components/schemas/requestPostOrPutGiftWrapping' required: - productId - quantity @@ -933,54 +1017,13 @@ components: variantId: type: number description: ID of the variant. + giftWrapping: + $ref: '#/components/schemas/requestPostOrPutGiftWrapping' required: - productId - quantity - variantId - title: Product with a variant - - properties: - productId: - type: number - description: ID of the product. - quantity: - type: number - description: Quantity of this item. - variantId: - type: number - optionSelections: - type: array - description: Array of `OptionSelection` objects. - items: - oneOf: - - type: object - properties: - optionId: - type: number - description: 'ID of the option, same as the `nameId`.' - example: 10 - - type: object - properties: - optionValue: - description: 'Value of the option, same as the `valueId`.' - oneOf: - - type: string - example: Small - - type: number - example: 127 - - type: object - properties: - month: - type: string - day: - type: string - year: - type: string - required: - - productId - - quantity - - variantId - - optionSelections - title: Custom product + title: Product with a variant x-examples: example-1: productId: 0 @@ -1039,13 +1082,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1148,13 +1185,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1257,13 +1288,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1426,119 +1451,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 - digitalItems: - - options: - - name: string - nameId: 0 - value: string - valueId: 0 - brand: string - couponAmount: 0 - discountAmount: 0 - discounts: - - discountedAmount: 0 - id: 0 - extendedListPrice: 0 - extendedSalePrice: 0 - id: '4' - imageUrl: 'http://example.com' - isTaxable: true - originalPrice: 0 - listPrice: 0 - name: string - parentId: '6' - productId: 0 - quantity: 0 - salePrice: 0 - sku: string - url: 'http://example.com' - variantId: 7 - giftCertificates: - - amount: 0 - id: string - isTaxable: true - message: string - name: string - recipient: - email: user@example.com - name: string - sender: - email: user@example.com - name: string - theme: string - physicalItems: - - options: - - name: string - nameId: 0 - value: string - valueId: 0 - brand: string - couponAmount: 0 - discountAmount: 0 - discounts: - - discountedAmount: 0 - id: string - extendedListPrice: 0 - extendedSalePrice: 0 - id: '4' - imageUrl: 'http://example.com' - isTaxable: true - originalPrice: 0 - listPrice: 0 - name: string - parentId: 6 - productId: 0 - quantity: 0 - salePrice: 0 - sku: string - url: 'http://example.com' - variantId: 7 - giftWrapping: null - isShippingRequired: true - createdTime: string - updatedTime: string - locale: string - deleteCarts: - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/responseCart' - examples: - example-1: - value: - id: string - customerId: 0 - email: string - currency: - code: string - isTaxIncluded: true - baseAmount: 0 - discountAmount: 0 - cartAmount: 0 - coupons: - - code: string - couponType: 0 - discountedAmount: 0 - id: string - discounts: - - discountedAmount: 0 - id: string - lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1622,5 +1535,4 @@ components: - lineItems.physicalItems.options - lineItems.digitalItems.options - 'lineItems.digitalItems.options,lineItems.physicalItems.options' - examples: {} diff --git a/reference/carts.v3.yml b/reference/carts.v3.yml index e02187f63..2ad220064 100644 --- a/reference/carts.v3.yml +++ b/reference/carts.v3.yml @@ -133,15 +133,15 @@ paths: product_id: 118 list_price: 30 name: shirt - options: - - name: Size - nameId: 125 - value: Large - valueId: 127 + option_selections: + - name: Color + value: Red + option_id: 133 + option_value: 149 - name: Add a $5 Donation - nameId: 126 - value: 'No' - valueId: 129 + value: No + option_id: 126 + option_value: 129 channel_id: 1 currency: code: AUD @@ -163,7 +163,7 @@ paths: message: Happy Birthday gift_certificates: - name: Tobi Day - theme: Birthday + theme: birthday.html amount: 1 quantity: 1 sender: @@ -288,6 +288,8 @@ paths: Overriding a product’s `list_price` will make that item ineligible for V3 product level promotions. If a product has modifiers, omit the `variant_id` and instead use the `option_selections` array to describe both the **variant** and the **modifier** selections. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. parameters: - name: include in: query @@ -320,7 +322,7 @@ paths: option_value: 'Yes' gift_certificates: - name: Happy Birthday - theme: Birthday + theme: birthday.html amount: 50 quantity: 1 sender: @@ -395,6 +397,8 @@ paths: `custom_items` cannot be updated via the API at this time. To update your cart, add a new updated custom item and delete the outdated one. If your cart contains only one line item, perform the add operation before the delete operation. Deleting all line items from the cart will invalidate the cart. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. parameters: - name: include in: query @@ -507,7 +511,7 @@ paths: gift_certificates: - id: 6e38bbc2-8873-472c-a452-8bd4aaea5d3a name: Happy Birthday - theme: Birthday + theme: birthday.html amount: 50 quantity: 1 taxable: false @@ -530,7 +534,7 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cartId' get: - description: Returns a storeʼs *Cart*. + description: Returns a store's *Cart*. parameters: - name: include in: query @@ -557,7 +561,7 @@ paths: operationId: getACart put: description: |- - Updates a *Cartʼs* `customer_id`. + Updates a *Cart's* `customer_id`. **Notes** @@ -792,7 +796,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -819,8 +823,15 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MetafieldPost' - examples: {} + $ref: '#/components/schemas/MetafieldPost' + example: + { + "permission_set": app_only, + "namespace": Sales Department, + "key": Staff Name, + "value": Sam, + "description": Name of staff member + } description: '' required: true responses: @@ -831,7 +842,19 @@ paths: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionResponse' - examples: {} + example: + data: + "id": 24 + "key": Staff Name + "value": Sam + "namespace": Sales Department + "permission_set": app_only + "resource_type": cart + "resource_id": b810114d-9926-45b7-bba5-7633b251154b + "description": Name of staff member + "date_created": 2023-11-15T15:16:35+00:00 + "date_modified": 2023-11-15T15:16:35+00:00 + meta: {} '404': description: | The resource was not found. @@ -862,7 +885,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -991,12 +1014,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1055,12 +1078,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1158,12 +1181,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1263,12 +1286,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1461,12 +1484,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number description: 'Value must be between 1.00 and 1,000.00 in the store’s default currency.' @@ -1505,7 +1528,7 @@ components: description: Name provided for the gift certificate that will appear in the control panel. theme: type: string - description: 'The theme of the gift certificate. The following options are available:`Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.' + description: 'The theme of the gift certificate. The following options are available:`birthday.html`, `boy.html`, `celebration.html`, `christmas.html`, `general.html`, and `girl.html`.' amount: type: number description: 'Value must be between 1.00 and 1,000.00 in the store’s default currency.' @@ -2103,7 +2126,7 @@ components: description: SKU of the variant. name: type: string - description: The item’s product name. + description: The item's product name. example: T-Shirt url: description: The product URL. @@ -2350,7 +2373,7 @@ components: type: object title: Item Custom description: |- - Add a custom item to the shopperʼs cart. + Add a custom item to the shopper's cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes. @@ -2374,7 +2397,7 @@ components: type: object title: Item Custom description: |- - Add a custom item to the shopperʼs cart. + Add a custom item to the shopper's cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes. @@ -2523,12 +2546,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -2590,12 +2613,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -2915,15 +2938,34 @@ components: type: string description: 'The product option name; for example, Color or Size.' nameId: - type: number + type: number + example: 151 description: The product option identifier. value: type: string description: 'The product option value; for example, Red or Medium.' valueId: - type: number + oneOf: + - type: number + example: 128 + - type: string + example: "1259" description: The product option value identifier in number format. - example: 128 + + gift_wrapping: + description: The gift wrapping details for this item. + type: object + properties: + name: + type: string + example: Gift Wrap 1 + message: + type: string + example: Happy Birthday! + amount: + type: number + format: float + example: 1.99 required: - variant_id - product_id @@ -2971,7 +3013,7 @@ components: date_created: type: string format: date-time - description: Date and time of the metafieldʼs creation. + description: Date and time of the metafield's creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string @@ -3117,9 +3159,7 @@ components: Response payload for the BigCommerce API. properties: data: - type: array - items: - $ref: '#/components/schemas/Metafield' + $ref: '#/components/schemas/Metafield' meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false @@ -3290,14 +3330,14 @@ components: MetafieldKeyParam: name: key in: query - description: Filter based on a metafieldʼs key. + description: Filter based on a metafield's key. required: false schema: type: string MetafieldNamespaceParam: name: namespace in: query - description: Filter based on a metafieldʼs key. + description: Filter based on a metafield's key. required: false schema: type: string @@ -3335,14 +3375,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/brands_catalog.v3.yml b/reference/catalog/brands_catalog.v3.yml index dc647edb7..6cdf70696 100644 --- a/reference/catalog/brands_catalog.v3.yml +++ b/reference/catalog/brands_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Brands description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Our Catalog Brands endpoints let you [create individual brands](/docs/rest-catalog/brands#create-a-brand) and [modify the brands](/docs/rest-catalog/brands#update-a-brand) associated with a store's products, along with [deleting brands](/docs/rest-catalog/brands#delete-a-brand). @@ -15,7 +15,7 @@ info: ## Resources ### Webhooks - * [Category](/api-docs/store-management/webhooks/events#category) + * [Category](/docs/integrations/webhooks/events#category) ### Additional Catalog endpoints * [Categories](/docs/rest-catalog/categories) @@ -591,7 +591,12 @@ paths: tags: - Brands summary: Delete Brands - description: 'By default, it deletes all *Brand* objects. A filter should be added to avoid deleting all *Brand* objects in a store.' + description: |- + To delete brand objects, you must include a filter. + + **Required Fields** + - name + operationId: deleteBrands parameters: - name: name @@ -600,6 +605,8 @@ paths: Filter items by name. schema: type: string + required: + true - name: page_title in: query description: | @@ -620,14 +627,6 @@ paths: description: Returns a single *Brand*. Optional filter parameters can be passed in. operationId: getBrandById parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -707,13 +706,6 @@ paths: operationId: updateBrand parameters: - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -975,14 +967,6 @@ paths: summary: Delete a Brand description: Deletes a *Brand*. operationId: deleteBrandById - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer responses: '204': description: '' @@ -998,14 +982,6 @@ paths: description: 'Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. ' operationId: getBrandMetafieldsByBrandId parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - - name: id in: query description: | @@ -1178,13 +1154,6 @@ paths: operationId: createBrandMetafield parameters: - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1509,13 +1478,6 @@ paths: operationId: createBrandImage parameters: - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: multipart/form-data: @@ -1602,14 +1564,6 @@ paths: summary: Delete a Brand Image description: Deletes a *Brand Image*. operationId: deleteBrandImage - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer responses: '204': description: '' @@ -1950,14 +1904,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/categories_catalog.v3.yml b/reference/catalog/categories_catalog.v3.yml index 9821fff1e..43996ff1b 100644 --- a/reference/catalog/categories_catalog.v3.yml +++ b/reference/catalog/categories_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Categories description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Our Catalog Categories endpoints let you [create individual categories](/docs/rest-catalog/categories#create-a-category) and [modify categories](/docs/rest-catalog/categories#update-a-category) that organize a store's products, as well as [delete categories](/docs/rest-catalog/categories#delete-a-category). @@ -12,14 +12,14 @@ info: This API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. - These endpoints are primarily useful in applications for single storefront stores. To work with categories for an [MSF-enabled store](/api-docs/multi-storefront/overview), see [Category Trees](/docs/rest-catalog/category-trees). + These endpoints are primarily useful in applications for single storefront stores. To work with categories for an [MSF-enabled store](/docs/storefront/multi-storefront), see [Category Trees](/docs/rest-catalog/category-trees). > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. ## Resources ### Webhooks - Learn more about [Category webhook events](/api-docs/store-management/webhooks/events#category). + Learn more about [Category webhook events](/docs/integrations/webhooks/events#category). ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -55,13 +55,17 @@ paths: tags: - Categories summary: Get All Categories - description: Returns a list of *Categories*. Optional filter parameters can be passed in. + description: |- + Returns a list of *Categories*. Optional filter parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: getCategories parameters: - name: id in: query description: | - Filter items by id. + Filter items by ID. schema: type: integer - name: 'id:in' @@ -215,6 +219,18 @@ paths: description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' schema: type: string + - name: sort + in: query + description: |- + Controls the sort order of the response, for example, `sort=name`. + + Allowed values: + - `name`: sort categories in alphabetical order by category name. + - `id`: sort in ascending order by category ID. + - `parent_id`: sort in ascending order by the ID of the parent category. + - `sort_order`: sort in ascending order by sort order value. + schema: + type: string responses: '200': description: '' @@ -353,7 +369,7 @@ paths: tags: - Categories summary: Create a Category - description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit." + description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n" operationId: createCategory parameters: - $ref: '#/components/parameters/ContentType' @@ -430,7 +446,7 @@ paths: minLength: 0 type: string description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). example: category.html is_visible: type: boolean @@ -453,7 +469,7 @@ paths: image_url: type: string description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' x-url: true custom_url: @@ -497,7 +513,7 @@ paths: meta: $ref: '#/components/schemas/metaEmpty_Full' '207': - description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' + description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' content: application/json: schema: @@ -570,7 +586,7 @@ paths: parameters: - name: id in: query - description: Filter items by id. + description: Filter items by ID. schema: type: integer - name: 'id:in' @@ -715,17 +731,13 @@ paths: tags: - Categories summary: Get a Category - description: Returns a single *Category*. Optional parameters can be passed in. + description: |- + Returns a single *Category*. Optional parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: getCategoryById parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -782,16 +794,12 @@ paths: **Read-Only Fields** - id + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: updateCategory parameters: - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -871,7 +879,7 @@ paths: minLength: 0 type: string description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). example: category.html is_visible: type: boolean @@ -894,7 +902,7 @@ paths: image_url: type: string description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' x-url: true custom_url: @@ -1009,7 +1017,7 @@ paths: minLength: 0 type: string description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). example: category.html is_visible: type: boolean @@ -1032,7 +1040,7 @@ paths: image_url: type: string description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' x-url: true custom_url: @@ -1142,16 +1150,12 @@ paths: tags: - Categories summary: Delete a Category - description: Deletes a *Category*. + description: |- + Deletes a *Category*. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: deleteCategoryById - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer responses: '204': description: '' @@ -1167,18 +1171,10 @@ paths: description: Returns a list of *Metafields* on a *Category*. Optional filter parameters can be passed in. operationId: getCategoryMetafieldsByCategoryId parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - name: id in: query description: | - Filter items by id. + Filter items by ID. schema: type: integer - name: 'id:in' @@ -1343,17 +1339,10 @@ paths: **Read-Only Fields** - id - **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. + **Note:** The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. operationId: createCategoryMetafield parameters: - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1450,21 +1439,6 @@ paths: description: Returns a single *Category Metafield*. Optional parameters can be passed in. operationId: getCategoryMetafieldByCategoryId parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -1529,20 +1503,6 @@ paths: operationId: updateCategoryMetafield parameters: - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1603,21 +1563,6 @@ paths: summary: Delete a Category Metafield description: Deletes a *Category Metafield*. operationId: deleteCategoryMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer responses: '204': description: '' @@ -1643,13 +1588,6 @@ paths: operationId: createCategoryImage parameters: - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: multipart/form-data: @@ -1736,16 +1674,8 @@ paths: tags: - Images summary: Delete a Category Image - description: Deletes a *Cateogory Image*. + description: Deletes a *Category Image*. operationId: deleteCategoryImage - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer responses: '204': description: '' @@ -1770,21 +1700,20 @@ paths: - Priority 2: Manually specified sort order on Product (Global) Level (UI/API). - Priority 3: Default sorting by Product ID (newly added products go first) (UI/API). operationId: getsortorders - parameters: - - name: category_id - in: path - description: The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer responses: '200': description: '' content: application/json: schema: - type: object - properties: {} + type: array + items: + type: object + properties: + product_id: + type: number + sort_order: + type: integer '404': description: The requested category was not found. content: @@ -1799,12 +1728,6 @@ paths: operationId: updatesortorder parameters: - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1922,7 +1845,7 @@ components: minLength: 0 type: string description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). example: category.html is_visible: type: boolean @@ -1945,7 +1868,7 @@ components: image_url: type: string description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' x-url: true custom_url: @@ -1956,7 +1879,7 @@ components: metafield_Base: title: metafield_Base type: object - description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false properties: key: @@ -2314,7 +2237,7 @@ components: minLength: 0 type: string description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). example: category.html is_visible: title: is_visible @@ -2331,7 +2254,7 @@ components: image_url: type: string description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' x-url: true meta_description: @@ -2366,7 +2289,7 @@ components: example: 2 responses: General207Status: - description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' + description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' content: application/json: schema: @@ -2419,14 +2342,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/category-trees_catalog.v3.yml b/reference/catalog/category-trees_catalog.v3.yml index 7fdcf16de..3ccc45690 100644 --- a/reference/catalog/category-trees_catalog.v3.yml +++ b/reference/catalog/category-trees_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Category Trees description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Our Catalog Category Trees endpoints are the more modern and performant counterparts to the [Categories endpoints](/docs/rest-catalog/categories). Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context. @@ -15,7 +15,7 @@ info: ## Resources ### Webhooks - Learn more about [Category Tree webhook events](/api-docs/channels/guide/webhooks#category-trees). + Learn more about [Category Tree webhook events](/docs/integrations/webhooks/events/channels#category-trees). ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -403,7 +403,7 @@ paths: example: - id: 0 name: string - channel_ids: + channels: - 0 responses: '200': @@ -580,7 +580,7 @@ components: - $ref: '#/components/schemas/default_product_sort' - type: object properties: - custom_url: + url: $ref: '#/components/schemas/Url' x-examples: {} CategoryUuidData: @@ -633,8 +633,6 @@ components: properties: tree_id: type: integer - required: - - tree_id CategoryData: allOf: - type: object @@ -663,7 +661,7 @@ components: type: boolean image_url: type: string - custom_url: + url: $ref: '#/components/schemas/Url' CategoryDataPUT: allOf: @@ -679,7 +677,7 @@ components: Url: type: object properties: - url: + path: type: string is_customized: type: boolean @@ -846,7 +844,7 @@ components: type: string minLength: 1 maxLength: 255 - channel_ids: + channels: type: array items: type: integer @@ -1121,14 +1119,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/product-modifiers_catalog.v3.yml b/reference/catalog/product-modifiers_catalog.v3.yml index 374c60cf9..d3978eb96 100644 --- a/reference/catalog/product-modifiers_catalog.v3.yml +++ b/reference/catalog/product-modifiers_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Product Modifiers description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Product Modifiers represent choices that the shopper can make to change how the merchant customizes or adds on to the product. Examples include shipping insurance, monograms, custom inseam length, and a color selection for an unfinished product. @@ -17,7 +17,7 @@ info: ## Resources ### Webhooks - Learn more about [Product webhook events](/api-docs/store-management/webhooks/webhook-events#products). + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -846,14 +846,6 @@ paths: description: Returns a single *Product Modifier*. Optional parameters can be passed in. operationId: getModifierById parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -906,13 +898,6 @@ paths: operationId: updateModifier parameters: - $ref: '#/components/parameters/ContentType' - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1486,14 +1471,6 @@ paths: summary: Delete a Modifier description: Deletes a *Product Modifier*. operationId: deleteModifierById - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer responses: '204': description: '' @@ -2848,14 +2825,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/product-variant-options_catalog.v3.yml b/reference/catalog/product-variant-options_catalog.v3.yml index 883191867..92c1b79fe 100644 --- a/reference/catalog/product-variant-options_catalog.v3.yml +++ b/reference/catalog/product-variant-options_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Product Variant Options description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Product Variant Options represent the different facets of a product. For example, size, color, fabric. Variant Option values are the actual sizes, colors, fabrics, that are available. [Product Variants]() consist of combinations of Variant Option values. @@ -24,7 +24,7 @@ info: ## Resources ### Webhooks - Learn more about [Product webhook events](/api-docs/store-management/webhooks/webhook-events#products). + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -796,14 +796,6 @@ paths: description: Returns a single *Variant Option*. Optional parameters can be passed in. operationId: getOptionById parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -860,13 +852,6 @@ paths: operationId: updateOption parameters: - $ref: '#/components/parameters/ContentType' - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer requestBody: content: application/json: @@ -1475,14 +1460,6 @@ paths: summary: Delete a Product Variant Option description: Deletes a *Variant Option*. operationId: deleteOptionById - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer responses: '204': description: '' @@ -2479,14 +2456,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/product-variants_catalog.v3.yml b/reference/catalog/product-variants_catalog.v3.yml index 4cb7c50aa..a6d88e506 100644 --- a/reference/catalog/product-variants_catalog.v3.yml +++ b/reference/catalog/product-variants_catalog.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Catalog - Product Variants description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). A Product Variant is a version of a product that has its own SKU. For example, a catalog might model a particular style of high-top sneakers that come in both red and blue as one product - high-tops - with two variants - red and blue. From a storefront point of view, Product Variants are often what shoppers seek. They are also the object that maps to SKUs and tracks inventory. A Product with one only Variant is a _base variant_. @@ -21,7 +21,7 @@ info: ## Resources ### Webhooks - Learn more about [Product webhook events](/api-docs/store-management/webhooks/webhook-events#products). + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -379,14 +379,6 @@ paths: description: Returns a single product *Variant*. Optional parameters can be passed in. operationId: getVariantById parameters: - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -473,13 +465,6 @@ paths: operationId: updateVariant parameters: - $ref: '#/components/parameters/ContentType' - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer requestBody: content: application/json: @@ -572,14 +557,6 @@ paths: summary: Delete a Product Variant description: Deletes a product *Variant*. operationId: deleteVariantById - parameters: - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer responses: '204': description: '' @@ -795,21 +772,6 @@ paths: description: Returns a single product variant *Metafield*. Optional parameters can be passed in. operationId: getVariantMetafieldByProductIdAndVariantId parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -875,20 +837,6 @@ paths: operationId: updateVariantMetafield parameters: - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer requestBody: content: application/json: @@ -949,21 +897,6 @@ paths: summary: Delete a Variant Metafield description: Deletes a product variant *Metafield*. operationId: deleteVariantMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer responses: '204': description: '' @@ -1178,7 +1111,8 @@ paths: type: string - name: product_id in: query - description: 'A comma-separated list of IDs of products whose variants were requested. For example:`?product_id=:id``?product_id:in=77,80,81`' + description: |- + A comma-separated list of IDs of products whose variants were requested. For example:`?product_id:in=77,80,81` schema: type: string responses: @@ -1281,7 +1215,7 @@ paths: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). x-nullable: true maximum: 2147483647 inventory_warning_level: @@ -1374,7 +1308,21 @@ paths: tags: - Variants (Batch) summary: Update Variants (Batch) - description: 'Updates a batch of `variant` objects. At the time of writing, the limit is 50 variants. This limit is subject to change.' + description: |- + Updates a batch of `variant` objects. Currently the limit is 50 variants however this is subject to change. + + **Required Fields** + + To update an existing variant: + * id (variant id) + + To create a new variant: + * product_id + * sku + * option_values + - id (option_value ID - Example: 146) + - option_id (Option ID - Example: 151) + operationId: updateVariantsBatch parameters: - $ref: '#/components/parameters/ContentType' @@ -1399,30 +1347,35 @@ paths: description: The cost price of the variant. Not affected by Price List prices. format: double x-nullable: true + example: 40 price: minimum: 0 type: number description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' format: double x-nullable: true + example: 40 sale_price: minimum: 0 type: number description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' format: double x-nullable: true + example: 40 retail_price: minimum: 0 type: number description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' format: double x-nullable: true + example: 40 weight: minimum: 0 type: number description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' format: double x-nullable: true + example: 5 width: minimum: 0 type: number @@ -1430,6 +1383,7 @@ paths: Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. format: double x-nullable: true + example: 5 height: minimum: 0 type: number @@ -1437,6 +1391,7 @@ paths: Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. format: double x-nullable: true + example: 5 depth: minimum: 0 type: number @@ -1444,6 +1399,7 @@ paths: Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. format: double x-nullable: true + example: 5 is_free_shipping: type: boolean description: | @@ -1467,6 +1423,7 @@ paths: type: string description: The UPC code used in feeds for shopping comparison sites and external channel integrations. x-nullable: true + example: "1234" inventory_level: type: integer description: |- @@ -1476,14 +1433,16 @@ paths: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). x-nullable: true maximum: 2147483647 + example: 21474 inventory_warning_level: type: integer description: 'When the variant hits this inventory level, it is considered low stock.' x-nullable: true maximum: 2147483647 + example: 5474 bin_picking_number: maxLength: 255 minLength: 0 @@ -1495,6 +1454,7 @@ paths: properties: id: type: integer + example: 154 x-required: - put required: true @@ -1598,7 +1558,7 @@ paths: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). x-nullable: true maximum: 2147483647 inventory_warning_level: @@ -1904,7 +1864,7 @@ components: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). nullable: true maximum: 2147483647 inventory_warning_level: @@ -2098,7 +2058,7 @@ components: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). nullable: true maximum: 2147483647 inventory_warning_level: @@ -2405,7 +2365,7 @@ components: name: product_id in: path description: | - The ID of the `Product` to which the resource belongs. + The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the `product_id` in the request path are successful as long as the parameter is not empty. The `product_id` segment is there only for path consistency. required: true schema: type: integer @@ -2456,14 +2416,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog/products_catalog.v3.yml b/reference/catalog/products_catalog.v3.yml index 189bd4044..d40fd8f66 100644 --- a/reference/catalog/products_catalog.v3.yml +++ b/reference/catalog/products_catalog.v3.yml @@ -2,11 +2,11 @@ openapi: '3.0.3' info: title: Catalog - Products description: |- - > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/api-docs/store-management/catalog/products-overview). + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). Our Catalog Products endpoints let you [create products](/docs/rest-catalog/products#create-a-product), perform [batch operations on existing products](/docs/rest-catalog/products#update-products-batch) and work with [reviews](/docs/rest-catalog/products/reviews), [images](/docs/rest-catalog/products/images), and [videos](/docs/rest-catalog/products/videos). Note that after a product is created initially, you can manage the nuances of its variations using the [Product Modifier](/docs/rest-catalog/product-modifiers), [Product Variant](/docs/rest-catalog/product-variants), and [Product Variant Options](/docs/rest-catalog/product-variant-options) endpoints. - Other core product endpoints focus on [bulk pricing](/docs/rest-catalog/products/bulk-pricing-rules), [complex rules](/docs/rest-catalog/products/complex-rules), [custom fields](/docs/rest-catalog/products/custom-fields), and [metafields](/docs/rest-catalog/products/metafields). Product Variant objects also contain [their own metafields](/docs/rest-catalog/product-variants/metafields). For [MSF-enabled](/api-docs/multi-storefront/overview) stores, the product object also contains product [channel assignments](/docs/rest-catalog/products/channel-assignments) and [category assignments](/docs/rest-catalog/products/category-assignments); read more about [products in the MSF context](/api-docs/multi-storefront/api-guide#products). + Other core product endpoints focus on [bulk pricing](/docs/rest-catalog/products/bulk-pricing-rules), [complex rules](/docs/rest-catalog/products/complex-rules), [custom fields](/docs/rest-catalog/products/custom-fields), and [metafields](/docs/rest-catalog/products/metafields). Product Variant objects also contain [their own metafields](/docs/rest-catalog/product-variants/metafields). For [MSF-enabled](/docs/storefront/multi-storefront) stores, the product object also contains product [channel assignments](/docs/rest-catalog/products/channel-assignments) and [category assignments](/docs/rest-catalog/products/category-assignments); read more about [products in the MSF context](/docs/storefront/multi-storefront/guide#products). This API family also contains an endpoint to [Get a catalog summary](/docs/rest-catalog/products/summary). @@ -15,8 +15,8 @@ info: ## Resources ### Webhooks - * [Product webhook events](/api-docs/store-management/webhooks/webhook-events#products) - * [Product assignment webhook events](/api-docs/channels/guide/webhooks#product-assignments) + * [Product webhook events](/docs/integrations/webhooks/events#products) + * [Product assignment webhook events](/docs/integrations/webhooks/events/channels#product-assignments) ### Additional Catalog endpoints * [Brands](/docs/rest-catalog/brands) @@ -290,18 +290,32 @@ paths: type: integer - name: include in: query - description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' + description: |- + Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page. + + **Note:** The following sub-resources include: + * variants + * images + * custom_fields + * bulk_pricing_rules + * primary_images + * modifiers + * options + * videos + explode: false schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos + type: array + items: + type: string + enum: + - variants + - images + - custom_fields + - bulk_pricing_rules + - primary_image + - modifiers + - options + - videos - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -329,7 +343,7 @@ paths: type: integer - name: limit in: query - description: Controls the number of items per page in a limited (paginated) list of products. + description: Controls the number of items per page in a limited (paginated) list of products. The default product limit is 50 with a maximum limit of 250. schema: type: integer - name: direction @@ -484,7 +498,7 @@ paths: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3 @@ -603,7 +617,7 @@ paths: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3 @@ -833,7 +847,7 @@ paths: example: errors: {} status: 413 - title: The request payload is too large. The maximum items allowed in the array is 50 + title: The request payload is too large. The maximum items allowed in the array is 10. type: /api-docs/getting-started/api-status-codes '422': description: '`Product` was not valid. This is the result of missing required fields or invalid data. See the response for more details.' @@ -864,6 +878,7 @@ paths: **Limits** - 250 characters product name length. + - A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB. **Usage Notes** * This endpoint accepts a `video` array. To create a product video that accepts a `video` object, see [Create a Product Video](/docs/rest-catalog/products/videos#create-a-product-video) for information. @@ -958,7 +973,7 @@ paths: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3.2 @@ -1276,6 +1291,16 @@ paths: Filter items by is_featured. schema: type: integer + - name: 'id:in' + in: query + description: + Filter by product ID(s). + style: form + explode: false + schema: + type: array + items: + type: integer - name: inventory_level in: query description: | @@ -1326,17 +1351,20 @@ paths: - name: include in: query description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' + explode: false schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos + type: array + items: + type: string + enum: + - variants + - images + - custom_fields + - bulk_pricing_rules + - primary_image + - modifiers + - options + - videos - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -1463,6 +1491,9 @@ paths: description: | Updates a *Product*. + **Limits** + - A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB. + **Read-Only Fields** - id - date_created @@ -1568,7 +1599,7 @@ paths: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3.2 @@ -1886,10 +1917,7 @@ paths: data: type: array items: - title: Product Image - type: object - allOf: - - $ref: '#/components/schemas/productImage_Full' + $ref: '#/components/schemas/productImage_Full' meta: $ref: '#/components/schemas/metaCollection_Full' description: | @@ -1965,9 +1993,10 @@ paths: **Usage Notes** - `image_url` - `255` character limit - - For file uploads, use the `multipart/form-data` media type - - Only one image at a time can be created + - For file uploads, use the `multipart/form-data` media type. + - You can create only one image at a time. A product can have up to 1000 images. - Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP. + - Each image file or image uploaded by URL can be up to 8 MB. operationId: createProductImage parameters: - $ref: '#/components/parameters/ContentType' @@ -1985,11 +2014,6 @@ paths: type: integer description: | The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - A `multipart/form-data` media type. url_zoom: readOnly: true type: string @@ -2039,7 +2063,9 @@ paths: image_file: type: string description: | - Must be sent as a multipart/form-data field in the request body. Limit of 1MB per file. + The local path to the original image file uploaded to BigCommerce. A `multipart/form-data` media type. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. multipart/form-data: schema: title: Product Image Post @@ -2056,11 +2082,6 @@ paths: type: integer description: | The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - A `multipart/form-data` media type. url_zoom: readOnly: true type: string @@ -2110,7 +2131,9 @@ paths: image_file: type: string description: | - Must be sent as a multipart/form-data field in the request body. Limit of 1MB per file. + The local path to the original image file uploaded to BigCommerce. A `multipart/form-data` media type. + + Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. required: true responses: '200': @@ -2136,12 +2159,6 @@ paths: type: integer description: | The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - - A `multipart/form-data` media type. url_zoom: readOnly: true type: string @@ -2197,6 +2214,8 @@ paths: description: |- The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. A `multipart/form-data` media type. + + Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. url_zoom: readOnly: true type: string @@ -2313,14 +2332,6 @@ paths: description: Returns a single *Product Image*. Optional parameters can be passed in. operationId: getProductImageById parameters: - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -2390,17 +2401,11 @@ paths: **Usage Notes** - `image_url` - `255` character limit + - Each image file or image uploaded by URL can be up to 8 MB. - For file uploads, send a POST request using the `multipart/form-data` media type operationId: updateProductImage parameters: - $ref: '#/components/parameters/ContentType' - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer requestBody: content: application/json: @@ -2431,10 +2436,6 @@ paths: type: integer description: | The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. url_zoom: readOnly: true type: string @@ -2489,6 +2490,8 @@ paths: type: string description: | The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. url_zoom: readOnly: true type: string @@ -2580,14 +2583,6 @@ paths: summary: Delete a Product Image description: Deletes a *Product Image*. operationId: deleteProductImage - parameters: - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer responses: '204': description: '' @@ -2857,13 +2852,6 @@ paths: description: Returns a single *Product Video*. Optional parameters can be passed in. operationId: getProductVideoById parameters: - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -2931,12 +2919,6 @@ paths: operationId: updateProductVideo parameters: - $ref: '#/components/parameters/ContentType' - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer requestBody: content: application/json: @@ -3077,13 +3059,6 @@ paths: summary: Delete a Product Video description: Deletes a *Product Video*. operationId: deleteProductVideo - parameters: - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer responses: '204': description: '' @@ -3542,14 +3517,6 @@ paths: description: Returns a single *Complex Rule*. Optional parameters can be passed in. operationId: getComplexRuleById parameters: - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -3743,14 +3710,6 @@ paths: operationId: updateComplexRule parameters: - $ref: '#/components/parameters/ContentType' - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer - requestBody: content: application/json: @@ -4074,14 +4033,6 @@ paths: summary: Delete a Complex Rule description: Deletes a product *Complex Rule*. operationId: deleteComplexRuleById - parameters: - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer responses: '204': description: '' @@ -4095,7 +4046,11 @@ paths: tags: - Custom Fields summary: Get Custom Fields - description: Returns a list of product *Custom Fields*. Optional parameters can be passed in. + description: |- + Returns a list of product *Custom Fields*. Optional parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: getCustomFields parameters: - name: include_fields @@ -4193,9 +4148,8 @@ paths: **Read-Only:** - id - **Limits** - - 200 custom fields per product limit. - - 255 characters per custom field limit. + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: createCustomField parameters: - $ref: '#/components/parameters/ContentType' @@ -4337,14 +4291,6 @@ paths: description: Returns a single *Custom Field*. Optional parameters can be passed in. operationId: getCustomFieldById parameters: - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -4409,13 +4355,6 @@ paths: operationId: updateCustomField parameters: - $ref: '#/components/parameters/ContentType' - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer requestBody: content: application/json: @@ -4554,16 +4493,12 @@ paths: tags: - Custom Fields summary: Delete a Custom Field - description: Deletes a product *Custom Field*. + description: |- + Deletes a product *Custom Field*. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: deleteCustomFieldById - parameters: - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer responses: '204': description: '`204 No Content`. Action has been enacted and no further information is to be supplied. `null` is returned.' @@ -4839,14 +4774,6 @@ paths: description: Returns a single *Bulk Pricing Rule*. Optional parameters can be passed in. operationId: getBulkPricingRuleById parameters: - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -4922,13 +4849,6 @@ paths: operationId: updateBulkPricingRule parameters: - $ref: '#/components/parameters/ContentType' - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer requestBody: content: application/json: @@ -5091,14 +5011,6 @@ paths: summary: Delete a Bulk Pricing Rule description: Deletes a *Bulk Pricing Rule*. operationId: deleteBulkPricingRuleById - parameters: - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer responses: '204': description: '' @@ -5346,14 +5258,6 @@ paths: description: Returns a single *Product Metafield*. Optional parameters can be passed in. operationId: getProductMetafieldByProductId parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -5419,13 +5323,6 @@ paths: operationId: updateProductMetafield parameters: - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer requestBody: content: application/json: @@ -5486,14 +5383,6 @@ paths: summary: Delete a Product Metafield description: Deletes a *Product Metafield*. operationId: deleteProductMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer responses: '204': description: '' @@ -5821,14 +5710,6 @@ paths: description: Returns a single *Product Review*. Optional parameters maybe passed in. operationId: getProductReviewById parameters: - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer - - name: include_fields in: query description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' @@ -5961,13 +5842,6 @@ paths: operationId: updateProductReview parameters: - $ref: '#/components/parameters/ContentType' - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer requestBody: description: | A BigCommerce `ProductReview` object. @@ -6134,14 +6008,6 @@ paths: summary: Delete a Product Review description: Deletes a *Product Review*. operationId: deleteProductReview - parameters: - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer responses: '204': description: '' @@ -6675,7 +6541,7 @@ components: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). nullable: true maximum: 2147483647 inventory_warning_level: @@ -6861,7 +6727,7 @@ components: If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). nullable: true maximum: 2147483647 inventory_warning_level: @@ -6987,7 +6853,9 @@ components: image_file: type: string description: | - The local path to the original image file uploaded to BigCommerce. Limit of 1MB per file. + The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. is_thumbnail: type: boolean description: | @@ -7868,7 +7736,7 @@ components: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3.2 @@ -8144,7 +8012,7 @@ components: open_graph_use_meta_description: true open_graph_use_product_name: true open_graph_use_image: true - brand_name or brand_id: Common Good + brand_name: Common Good gtin: string mpn: string reviews_rating_sum: 3.2 @@ -8207,7 +8075,7 @@ components: minLength: 0 type: string description: | - A unique user-defined product code/stock keeping unit (SKU). + A unique user-defined alphanumeric product code/stock keeping unit (SKU). example: SM-13 description: type: string @@ -8270,9 +8138,9 @@ components: type: number description: Minimum Advertised Price tax_class_id: - maximum: 1000000000 + maximum: 255 minimum: 0 - type: integer + type: number description: | The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.) product_tax_code: @@ -8280,7 +8148,7 @@ components: minLength: 0 type: string description: | - Accepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce's Avalara Premium integration can calculate sales taxes more accurately. Stores without Avalara Premium will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see Avalara's documentation. + Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerce's Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax provider's documentation. categories: type: array description: | @@ -8288,13 +8156,19 @@ components: x-required: - post items: - type: integer + type: number + maximum: 1000 + minimum: 0 brand_id: maximum: 1000000000 minimum: 0 type: integer description: | - A product can be added to an existing brand during a product /PUT or /POST. + You can add a product to an existing brand during a product /PUT or /POST. Use either the `brand_id` or the `brand_name` field. The response body can include `brand_id`. + brand_name: + type: string + description: You can create the brand during a product PUT or POST request. If the brand already exists, the product /PUT or /POST request adds the product to the brand. If not, the product /PUT or /POST request creates the brand and then adds the product to the brand. Brand name is not case-sensitive; "Common Good" and "Common good" are the same. Use either the `brand_id` or the `brand_name` field. The response body does not include `brand_name`. + example: Common Good inventory_level: maximum: 2147483647 minimum: 0 @@ -8304,7 +8178,7 @@ components: The inventory for a product cannot exceed 2,147,483,647 in the catalog. If you exceed the limit, the store sets the inventory level to the limit. - The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/buy-online-pick-up-in-store/inventory#limit-handling-in-inventory-versus-catalog-api). + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). inventory_warning_level: maximum: 2147483647 minimum: 0 @@ -8391,6 +8265,8 @@ components: type: string description: | Type of gift-wrapping options. Values: `any` - allow any gift-wrapping options in the store; `none` - disallow gift-wrapping on the product; `list` – provide a list of IDs in the `gift_wrapping_options_list` field. + + Always included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters. enum: - any - none @@ -8399,14 +8275,16 @@ components: type: array description: | A list of gift-wrapping option IDs. + + Always included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters. items: type: integer sort_order: - maximum: 2147483647 - minimum: -2147483648 type: integer description: | Priority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results. + maximum: 2147483647 + minimum: -2147483648 condition: type: string description: | @@ -8439,6 +8317,8 @@ components: Custom title for the product page. If not defined, the product name will be used as the meta title. meta_keywords: type: array + maxLength: 65535 + minLength: 0 description: | Custom meta keywords for the product page. If not defined, the store's default keywords will be used. items: @@ -8455,6 +8335,7 @@ components: type: integer description: | The number of times the product has been viewed. + deprecated: true preorder_release_date: type: string description: | @@ -8519,10 +8400,6 @@ components: type: boolean description: | Flag to determine if product image or open graph image is used. - brand_name or brand_id: - type: string - description: The brand can be created during a product PUT or POST request. If the brand already exists then the product will be added. If not the brand will be created and the product added. If using `brand_name` it performs a fuzzy match and adds the brand. eg. "Common Good" and "Common good" are the same. Brand name does not return as part of a product response. Only the `brand_id`. - example: Common Good gtin: type: string description: Global Trade Item Number @@ -8546,6 +8423,9 @@ components: example: 80 custom_fields: type: array + minimum: 0 + maximum: 255 + description: 200 maximum custom fields per product. 255 maximum characters per custom field. The default rate limit for this endpoint is 40 concurrent requests. items: $ref: '#/components/schemas/productCustomField_Put' bulk_pricing_rules: @@ -8847,14 +8727,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/channels.v3.yml b/reference/channels.v3.yml index b018e5da6..8e5b6ff44 100644 --- a/reference/channels.v3.yml +++ b/reference/channels.v3.yml @@ -8,7 +8,7 @@ info: email: support@bigcommerce.com title: Channels description: |- - Create and manage sales [channels](/api-docs/channels/overview), their [sites](/docs/rest-management/channels/channel-site), and their [product listings](/docs/rest-management/channels/channel-listings). + Create and manage sales [channels](/docs/integrations/channels), their [sites](/docs/rest-management/channels/channel-site), and their [product listings](/docs/rest-management/channels/channel-listings). ## Channels @@ -18,34 +18,43 @@ info: A channel's `type` and `platform` combination must be a valid pair as indicated in the table below. - | Platform | Accepted Type | - |-------------------|---------------------------| - | `square` | `pos` | - | `stripe` | `pos` | - | `vend` | `pos` | - | `clover` | `pos` | - | `talech` | `pos` | - | `facebook by meta`| `marketplace`,`marketing` | - | `instagram by meta`| `marketplace`,`marketing`| - | `amazon` | `marketplace` | - | `ebay` | `marketplace` | - | `pinterest` | `marketplace` | - | `wayfair` | `marketplace` | - | `overstock` | `marketplace` | - | `etsy` | `marketplace` | - | `wish` | `marketplace` | - | `walmart` | `marketplace` | - | `bigcommerce` | `storefront` | - | `gatsby` | `storefront` | - | `wordpress` | `storefront` | - | `drupal` | `storefront` | - | `acquia` | `storefront` | - | `bloomreach` | `storefront` | - | `deity` | `storefront` | - | `next` | `storefront` | - | `vue` | `storefront` | - | `google_shopping` | `marketing` | - | `custom` | `storefront`, `pos`, `marketing`, `marketplace` | + | Platform | Accepted Type | + |:--------------------|:--------------| + | `clover` | `pos` | + | `square` | `pos` | + | `stripe` | `pos` | + | `talech` | `pos` | + | `vend` | `pos` | + | `amazon` | `marketplace` | + | `belk` | `marketplace` | + | `catch` | `marketplace` | + | `ebay` | `marketplace` | + | `etsy` | `marketplace` | + | `facebook` | `marketplace`, `marketing` | + | `hudsons_bay` | `marketplace` | + | `google` | `marketplace`, `marketing` | + | `google_shopping` (deprecated) | `marketing` | + | `instagram` | `marketplace`, `marketing` | + | `macys` | `marketplace` | + | `mirakl` | `marketplace` | + | `overstock` | `marketplace` | + | `pinterest` | `marketplace` | + | `target_plus` | `marketplace` | + | `tiktok` | `marketplace` | + | `wayfair` | `marketplace` | + | `wish` | `marketplace` | + | `walmart` | `marketplace` | + | `acquia` | `storefront` | + | `bigcommerce` | `storefront` | + | `bloomreach` | `storefront` | + | `deity` | `storefront` | + | `drupal` | `storefront` | + | `gatsby` | `storefront` | + | `next` | `storefront` | + | `vue` | `storefront` | + | `wordpress` | `storefront` | + | `custom` | `storefront`, `pos`, `marketing`, `marketplace` | + ### Status @@ -72,9 +81,9 @@ info: ## Resources * [Sites and Routes API Reference](/docs/rest-management/sites) - * [Building Channels Overview](/api-docs/channels/overview) - * [Building Channel Apps](/api-docs/channels/building-channel-apps) - * [Channels Toolkit Reference](/api-docs/channels/channels-toolkit-reference) + * [Building Channels Overview](/docs/integrations/channels) + * [Building Channel Apps](/docs/integrations/channels/guide) + * [Channels Toolkit Reference](/docs/integrations/channels/toolkit-reference) servers: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' variables: @@ -243,7 +252,7 @@ paths: - $ref: '#/components/parameters/ContentType' summary: Create Multiple Channels Currency Assignments operationId: createMultipleChannelsCurrencyAssignments - description: Sets enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Sets enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -265,7 +274,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: updateMultipleChannelsCurrencyAssignments - description: Updates enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Updates enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -302,7 +311,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: createSingleChannelCurrencyAssignments - description: Sets enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Sets enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -324,7 +333,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: updateSingleChannelCurrencyAssignments - description: Updates enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Updates enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -1296,7 +1305,7 @@ components: content: application/json: schema: - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false type: object properties: @@ -2013,15 +2022,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -2300,11 +2309,11 @@ components: properties: app: type: object - description: 'A [channel app](/api-docs/channels/overview#channel-apps) config object for optionally configuring the channelʼs user interface in the control panel.' + description: 'A [channel app](/docs/integrations/channels#channel-apps) config object for optionally configuring the channelʼs user interface in the control panel.' properties: id: type: integer - description: 'The unique `id` given to an app registered in [DevTools](https://devtools.bigcommerce.com/); used to create links to the app in channel manager. `app.id` is optional; however, if youʼre building an app that creates or manages a channel, we recommend including it to ensure the user interface in the control panel works properly. Select partners who are promoted in the Channel Manager must build an app, and include the app ID in the create channel request. [Learn how to find an Appʼs ID](/api-docs/apps/tutorials/id).' + description: 'The unique `id` given to an app registered in [DevTools](https://devtools.bigcommerce.com/); used to create links to the app in channel manager. `app.id` is optional; however, if youʼre building an app that creates or manages a channel, we recommend including it to ensure the user interface in the control panel works properly. Select partners who are promoted in the Channel Manager must build an app, and include the app ID in the create channel request. [Learn how to find an Appʼs ID](/docs/integrations/apps/guide/id).' sections: type: array description: 'Sections are now deprecated under config_meta. The new /channel-menus endpoints should be used instead. If set, when the app is loaded within the control panel, the navigation `sections` will be directly embedded in the control panel navigation.' @@ -2634,7 +2643,7 @@ components: x-internal: false BigCommerceProtectedAppSections: type: array - description: 'List of channel-specific control panel menu navigation items and corresponding settings pages an app developer can choose to enable for the subject channel. Protected settings override any settings set in those UI sections at the storewide level. Learn more in the [Building Storefront Channels](/api-docs/channels/tutorials/storefront#protected-ui-sections) tutorial.' + description: 'List of channel-specific control panel menu navigation items and corresponding settings pages an app developer can choose to enable for the subject channel. Protected settings override any settings set in those UI sections at the storewide level. Learn more in the [Building Storefront Channels](/docs/integrations/channels/guide/storefronts#protected-ui-sections) tutorial.' items: type: string enum: @@ -2925,7 +2934,7 @@ components: metafield_Post: title: metafield_Post type: object - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false properties: namespace: @@ -2987,7 +2996,7 @@ components: metafield_Put: title: metafield_Put type: object - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false properties: namespace: diff --git a/reference/checkouts.sf.yml b/reference/checkouts.sf.yml index ab4838cec..2d72c25b2 100644 --- a/reference/checkouts.sf.yml +++ b/reference/checkouts.sf.yml @@ -5,9 +5,9 @@ info: Manage checkout operations and data using front-end JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -373,11 +373,12 @@ paths: description: |- Updates a *Checkout Line Item*. Updates an existing, single line item in the cart. - If a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoint or the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout). + If a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoint or the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsCartsItemsItemIdByCheckoutIdAndCartIdPut parameters: - name: checkoutId @@ -1201,7 +1202,7 @@ paths: * Required Fields: * `shipping_address` (deprecated) or `address` * `lineItems` - 2. Update the Consignment with Shipping Options using the [REST Storefront API](/checkouts/checkout-consignments#update-a-consignment), the [REST Management API](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) or the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout). + 2. Update the Consignment with Shipping Options using the [REST Storefront API](/checkouts/checkout-consignments#update-a-consignment), the [REST Management API](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) or the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). ### For **pickup** consignments: 1. Create a new consignment object. @@ -1211,11 +1212,12 @@ paths: * `pickupOption` * `lineItems` - To learn more about creating a Checkout Consignment, see the [Carts and Checkouts Tutorial](/api-docs/storefront/tutorials/carts). + To learn more about creating a Checkout Consignment, see the [Carts and Checkouts Tutorial](/docs/storefront/cart-checkout/guide/rest-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsConsignmentsByCheckoutIdPost parameters: - name: checkoutId @@ -1379,12 +1381,13 @@ paths: * `shippingOptionId` or `pickupOptionId` * `lineItems` - To learn more about creating a Checkout Consignment see [Checkout Consignment API](/api-docs/checkouts/checkout-consignment). + To learn more about creating a Checkout Consignment see [Checkout Consignment API](/docs/storefront/cart-checkout/guide/consignments). - > #### Note + > #### Notes > * You cannot pass both an `address` and a `shippingOptionId` because the shipping option may not be available for the new address > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsConsignmentsByCheckoutIdAndConsignmentIdPut parameters: - name: checkoutId @@ -2845,6 +2848,9 @@ components: type: number description: The total value of all coupons applied to this item. format: double + originalPrice: + type: number + description: The item’s original price is the same as the product’s default price. listPrice: type: number description: The item’s list price, as quoted by the manufacturer or distributor. @@ -2954,6 +2960,9 @@ components: type: number description: The total value of all coupons applied to this item. format: double + originalPrice: + type: number + description: The item’s original price is the same as the product’s default price. listPrice: type: number description: The item’s list price, as quoted by the manufacturer or distributor. @@ -3420,6 +3429,8 @@ components: type: number description: '' format: double + giftWrapping: + $ref: '#/components/schemas/cartLineItemGiftWrapping_Put' x-internal: false cartLineItemGiftCertificate_Put: title: cartLineItemGiftCertificate_Put @@ -3452,6 +3463,39 @@ components: description: '' format: double x-internal: false + cartLineItemGiftWrapping_Put: + title: Gift Wrapping Request Data + required: + - wrapTogether + - wrapDetails + type: object + nullable: true + description: if passing null, it will remove the current gift wrapping for the item + properties: + wrapTogether: + type: boolean + description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually. + example: true + wrapDetails: + type: array + description: |- + Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value. + If wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. + (e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping) + If wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped + items: + type: object + required: + - id + properties: + id: + type: integer + description: Identifier of the gift wrapping option selected. + example: 0 + message: + type: string + description: Custom gift message. + example: Happy Birthday CreateConsignmentRequest: title: Create Consignment Request type: object diff --git a/reference/checkouts.v3.yml b/reference/checkouts.v3.yml index 038299a73..a15e535ea 100644 --- a/reference/checkouts.v3.yml +++ b/reference/checkouts.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Checkouts description: |- - For more information on authenticating BigCommerce APIs, see [Authentication](/api-docs/getting-started/authentication). + For more information on authenticating BigCommerce APIs, see [Authentication](/docs/start/authentication). Create and manage checkouts from existing carts using BigCommerce checkout logic. version: '3.0' @@ -1598,7 +1598,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/discounts': post: tags: @@ -2383,7 +2382,6 @@ paths: - homepage - cartpage text: Some text - x-codegen-request-body-name: body '/checkouts/{checkoutId}/billing-address': post: tags: @@ -3154,7 +3152,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/billing-address/{addressId}': put: tags: @@ -3925,7 +3922,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/consignments': post: tags: @@ -3934,7 +3930,10 @@ paths: description: |- Adds a new consignment to a checkout. - For more information about working with consignments, see [Checkout consignment](/api-docs/checkouts/checkout-consignment). + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. + + For more information about working with consignments, see [Checkout consignment](/docs/storefront/cart-checkout/guide/consignments). Though the only required `address` properties to create a consignment are `email` and `country_code`, to successfully [create an order](/docs/rest-management/checkouts/checkout-orders#create-an-order) the `address` requires the following properties: * `first_name` @@ -3964,8 +3963,36 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CreateConsignmentRequest' - required: true + $ref: '#/components/schemas/CreateConsignmentRequest' + examples: + Shipping Consignment: + value: + - address: + first_name: "Jane" + last_name: "Doe" + email: "Jane.Doe@email.com" + company: "BigCommerce" + address1: "100 Main Street" + address2: "string" + city: "Austin" + state_or_province: "Texas" + state_or_province_code: "string" + country_code: "US" + postal_code: "78701" + phone: "555-555-5555" + custom_fields: + - field_id: "string" + field_value: "string" + line_items: + item_id: "118f8774-387c-485e-a095-6ef76d5f1bbd" + quantity: 1 + Pickup Consignment: + value: + - line_items: + - item_id: "118f8774-387c-485e-a095-6ef76d5f1bbd" + quantity: 1 + pickup_option: + pickup_method_id: 1 responses: '200': description: '' @@ -4714,7 +4741,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/consignments/{consignmentId}': parameters: @@ -4730,13 +4756,18 @@ paths: - Checkout Consignments summary: Update Checkout Consignment description: |- - Updates an existing consignment. The address, line item IDs, and the shipping option ID can be updated using this endpoint. + Updates an existing consignment. The address, line item IDs, and shipping option ID can be updated using this endpoint. + + Use a separate `PUT` request to update the shipping option IDs if you also want to update the address and line item IDs. - To add a new address and shipping options with line items, complete the following steps. + To add new shipping options, complete the following steps: + * Use the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint to add a new [consignment] to a checkout. + * Assign a shipping option to the new consignment by sending a `PUT` request to update the consignment's `shipping_option_id` with a returned value from `data.consignments[N].available_shipping_option[N].id` obtained in the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. - 1. Add a new [consignment](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) to a checkout. + To update an existing address and line item IDs, assign a new address and line item IDs by sending a `PUT` request. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. - 2. Assign a shipping option to the new consignment by sending a `PUT` request to update the consignment's `shipping_option_id` with a returned value from `data.consignments[N].available_shipping_option[N].id` obtained in Step One. operationId: CheckoutsConsignmentsByCheckoutIdAndConsignmentIdPut parameters: - $ref: '#/components/parameters/Content-Type' @@ -5501,7 +5532,6 @@ paths: - homepage - cartpage text: Some text - x-codegen-request-body-name: body delete: tags: - Checkout Consignments @@ -7025,7 +7055,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/coupons/{couponCode}': delete: tags: @@ -8696,6 +8725,7 @@ components: format: int32 pickup_option: type: object + description: 'Assigns a pickup consignment. Note: You cannot assign a shipping method with a pickup consignment.' properties: pickup_method_id: type: integer @@ -8703,10 +8733,8 @@ components: x-internal: false UpdateConsignmentRequest: title: Update Consignment Request - type: array - items: - type: object - properties: + type: object + properties: address: title: Address Properties required: @@ -9699,14 +9727,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/consent.sf.yml b/reference/consent.sf.yml index 010aa62dc..a026f8030 100644 --- a/reference/consent.sf.yml +++ b/reference/consent.sf.yml @@ -10,9 +10,9 @@ info: description: |- Specify shopper cookie consent preferences. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: Storefront tags: - name: Consent @@ -73,7 +73,7 @@ components: 3 - Analytics 4 - Targeting; Advertising - For further definition of these categories, see [Scripts API](/api-docs/store-management/scripts). + For further definition of these categories, see [Scripts API](/docs/integrations/scripts). properties: allow: type: array diff --git a/reference/currencies.v2.yml b/reference/currencies.v2.yml index 740ec4b3b..83063f2bf 100644 --- a/reference/currencies.v2.yml +++ b/reference/currencies.v2.yml @@ -10,13 +10,13 @@ info: | -- | -- | | Default Currency | Storeʼs default currency is the one from which any auto-conversion of pricing (product, tax, shipping, promotions) will happen.| | Display Currency | Currency that is displayed on the storefront. This might or might not mean that shopper can actually transact in that currency. Display currency is also often called "presentment currency" in the payments industry. | - | Transactional Currency | Transactional currency is what currency and amount BC passes to the payment provider and the currency/amount that the shopper will be charged to their bank account. If thereʼs a discrepancy between the storefront display currency and the transactional currency, a shopper has to pay a conversion fee and the conversion rate that will be used will be outside of BCʼs purview. | - | Settlement Currency | This is the currency in which the merchant gets paid out to their bank account. If thereʼs a discrepancy between the currency that shopper transacts in and the currency in which merchant settles, merchant has to pay a conversion fee and the conversion rate used will be outside of BCʼs purview. Merchant is able to set their settlement currency through their payment provider. | + | Transactional Currency | Transactional currency is what currency and amount BigCommerce passes to the payment provider and the currency/amount that the shopper will be charged to their bank account. If thereʼs a discrepancy between the storefront display currency and the transactional currency, a shopper has to pay a conversion fee and the conversion rate that will be used will be outside of BigCommerceʼs purview. | + | Settlement Currency | This is the currency in which the merchant gets paid out to their bank account. If thereʼs a discrepancy between the currency that shopper transacts in and the currency in which merchant settles, merchant has to pay a conversion fee and the conversion rate used will be outside of BigCommerceʼs purview. Merchant is able to set their settlement currency through their payment provider. | |BigCommerce Conversion Rate | Any conversion rate set on BigCommerce used to convert product’s default currency pricing into a new non-default currency. Conversion rate could be static or dynamic. | | Static Conversion Rate | One of the two auto-converted pricing options. If a merchant manually enters a static conversion rate, then the conversion rate will remain the same until/unless merchant updates their currency settings to use a different conversion rate. The advantage of using this method is to avoid constantly fluctuating price in non-default currencies. | | Dynamic Conversion Rate | One of the two auto-converted pricing options. If a merchant selects a dynamic conversion rate, theyʼve tied themselves to a currency conversion service, which will update the conversion rate at a certain frequency. This helps shopper-facing pricing remain most aligned to the storeʼs default currency and keeps non-default currency conversion rate at market rate. Merchant can either use BigCommerce Currency Service provided in the Currency setup page, or they can use API to automatically update the exchange rate from their trusted source. | - | Bank Conversion Rate | Conversion rate used by merchant’s or shopper’s payment or credit card provider when auto-converting from store’s transactional currency. This rate might not align to the BC conversion rate and BC has no visibility into it. | - | Multi Currency Pricing | Rather than opting for auto-converting product pricing from default currency using BC conversion rate, merchant has a choice to set price per product per currency. This will be implemented through price lists. | + | Bank Conversion Rate | Conversion rate used by merchant’s or shopper’s payment or credit card provider when auto-converting from store’s transactional currency. This rate might not align with the BigCommerce conversion rate and BigCommerce has no visibility into it. | + | Multi Currency Pricing | Rather than opting for auto-converting product pricing from default currency using BigCommerce conversion rate, merchant has a choice to set price per product per currency. This will be implemented through price lists. | ## FAQ @@ -26,11 +26,11 @@ info: ## Resources - - [How Currencies Work](/api-docs/catalog/currencies/how-currencies-work) - - [Price List API](/docs/rest-management/price-lists) - - [Using Price Lists](https://support.bigcommerce.com/s/article/Price-Lists) (BigCommerce Knowledge Base) - - [Managing Currencies](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta) (BigCommerce Knowledge Base) - - [Tax](https://support.bigcommerce.com/s/article/Manual-Tax-Setup#intro1) (BigCommerce Knowledge Base) + - [How Currencies Work](/docs/store-operations/currencies/guide) + - [Price List API Reference](/docs/rest-management/price-lists) + - [Using Price Lists (Help Center)](https://support.bigcommerce.com/s/article/Price-Lists) + - [Managing Currencies (Help Center)](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta) + - [Tax (Help Center)](https://support.bigcommerce.com/s/article/Manual-Tax-Setup#intro1) version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -52,7 +52,6 @@ tags: paths: /currencies: parameters: - - $ref: '#/components/parameters/Accept' get: tags: @@ -60,6 +59,23 @@ paths: summary: Get All Currencies description: Returns a list of all store *Currency*. operationId: getAllCurrencies + parameters: + - name: page + description: | + Specifies the page number in a limited (paginated) list of currencies. + required: false + in: query + schema: + type: integer + default: 1 + - name: limit + description: | + Controls the number of items per page in a limited (paginated) list of currencies. + required: false + in: query + schema: + type: integer + default: 50 responses: '200': description: "" @@ -94,7 +110,7 @@ paths: * date_modified - The `is_default` property can only be set to true. The value of `is_default` cannot be unset, only overridden. To change the storeʼs default currency in the BigCommerce control panel, please see [Managing Currencies](https://support.bigcommerce.com/articles/Public/Managing-Currencies/?q=currency&l=en_US&fs=Search&pn=1#default). + The `is_default` property can only be set to true. The value of `is_default` cannot be unset, only overridden. To change the storeʼs default currency in the BigCommerce control panel, please see [Managing Currencies (Help Center)](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta). parameters: - $ref: '#/components/parameters/ContentType' requestBody: @@ -125,7 +141,6 @@ paths: type: object /currencies/{id}: parameters: - - $ref: '#/components/parameters/Accept' - name: id in: path @@ -202,14 +217,14 @@ components: currency_Base: title: currency_Base required: - - currency_code - - currency_exchange_rate - - decimal_places - - decimal_token - - name - - thousands_token - - token - - token_location + - currency_code + - currency_exchange_rate + - decimal_places + - decimal_token + - name + - thousands_token + - token + - token_location type: object properties: is_default: @@ -375,14 +390,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/current_customer.yml b/reference/current_customer.yml index 4f36e79be..a91f0fe60 100644 --- a/reference/current_customer.yml +++ b/reference/current_customer.yml @@ -4,11 +4,11 @@ info: description: |- Identify logged-in customers securely via JavaScript. - [Learn more about the current customer API](/api-docs/customers/current-customer-api). + [Learn more about the current customer API](/docs/start/authentication/current-customer). - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#client-id). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#client-id). > #### Note > * Substitute your storefront domain for `yourstore.example.com`. diff --git a/reference/custom-template-associations.v3.yml b/reference/custom-template-associations.v3.yml index d44236052..96c1d33ea 100644 --- a/reference/custom-template-associations.v3.yml +++ b/reference/custom-template-associations.v3.yml @@ -109,7 +109,7 @@ info: * [Get Channel Active Theme](/docs/rest-management/channels/channel-active-theme#get-a-channel-active-theme) * [Get Available Custom Templates](/docs/rest-content/themes/theme-custom-templates#get-custom-templates) - * [Catalog API](/docs/rest-management/catalog) + * [Catalog API](/docs/rest-catalog) * [Pages API](/docs/rest-content/pages) * [Channels API](/docs/rest-management/channels) termsOfService: 'https://www.bigcommerce.com/terms' @@ -477,14 +477,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/customer_login.yml b/reference/customer_login.yml index de2d3cc73..e147e457b 100644 --- a/reference/customer_login.yml +++ b/reference/customer_login.yml @@ -4,11 +4,11 @@ info: description: |- Enable single sign-on for shoppers on BigCommerce hosted storefronts. - [Learn more about the customer login API](/api-docs/customers/customer-login-api). + [Learn more about the customer login API](/docs/start/authentication/customer-login). - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#user-generated-jwts). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#user-generated-jwts). termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -32,7 +32,7 @@ paths: description: |- The customer login access point URL. - [Learn more about the Customer Login API](/api-docs/customers/customer-login-api). + [Learn more about the Customer Login API](/docs/start/authentication/customer-login). ## Example diff --git a/reference/customers.sf.yml b/reference/customers.sf.yml index 190877e28..a4b53ddf2 100644 --- a/reference/customers.sf.yml +++ b/reference/customers.sf.yml @@ -5,9 +5,9 @@ info: description: |- Manage customers and data via front-end JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). servers: - url: 'https://{store_domain}/api/storefront' variables: diff --git a/reference/customers.v2.yml b/reference/customers.v2.yml index e7c50bf77..9eb01a4eb 100644 --- a/reference/customers.v2.yml +++ b/reference/customers.v2.yml @@ -2,31 +2,32 @@ openapi: '3.0.1' info: title: Customers V2 description: |- - Create and Manage Customers, Customer Addresses, and Customer Groups. Additionally, validate customer passwords. To learn more about Customers see [here](/api-docs/customers/customers-subscribers-overview). + Create and Manage Customers, Customer Addresses, and Customer Groups. Additionally, validate customer passwords. To learn more about Customers see [here](/docs/store-operations/customers/customers-subscribers-overview). ## Available Endpoints | Resource / Endpoint | Description | - |-----------------------------------------|-------------------------------------------------------------------------------| + |:----------------------------------------|:------------------------------------------------------------------------------| | Customers | Identity and account details for customers shopping on BigCommerce stores | - | Customers Addresses | Postal address belonging to a customer. | + | Customers Addresses | Postal address belonging to a customer | | Customers Groups | Groupings of customers who share the same level of access and discounts | | Customers Validate Password | Validate customer passwords | ## Usage Notes **Customer Groups** * Customer Groups are only available on specific plans. + **Customers vs. Subscribers** * A subscriber is not always a customer. Someone can sign up for the newsletter only and not create an account. * A customer is not always a subscriber. Signing up for the newsletter is a separate action from creating an account and purchasing an item. * A customer and a subscriber can be the same. If a shopper checks out on the storefront, creates an account and opts into the newsletter, they are a customer and a subscriber. ## Resources ### Related APIs / Endpoints - [Customer Login API](/api-docs/customers/customer-login-api) - - [Current Customer API](/api-docs/customers/current-customer-api) + - [Customer Login API](/docs/start/authentication/customer-login) + - [Current Customer API](/docs/start/authentication/current-customer) - [Customers API (v3)](/docs/rest-management/customers) - [Subscribers API](/docs/rest-management/subscribers) ### Webhooks - - [Customers](/api-docs/store-management/webhooks/webhook-events#customer) + - [Customers](/docs/integrations/webhooks/events#customer) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -55,7 +56,7 @@ paths: tags: - Customers summary: Get All Customers - description: 'Returns a list of all *Customers*. Default sorting is by customer id, from lowest to highest. Optional parameters can be passed in.' + description: Returns a list of all *Customers*. Default sorting is by `customer_ID`, from lowest to highest. Optional parameters can be passed in. operationId: getAllCustomers parameters: - name: first_name @@ -165,12 +166,13 @@ paths: ``` ## Forcing Password Resets To force a customer to reset their password upon their next login attempt, give the `force_reset` field a value of true, as shown here: - ```json + ```js showLineNumbers copy { "_authentication": { "force_reset": true } } + ``` operationId: createANewCustomer parameters: - $ref: '#/components/parameters/ContentType' @@ -183,7 +185,7 @@ paths: _authentication: type: object properties: {} - description: 'This can vary depending on the action being taken to update, validate or force a password change. See Update Customer' + description: This can vary depending on the action being taken to update, validate or force a password change. See [Customers V2, Update a customer (Deprecated)](/docs/rest-management/customers-v2#update-a-customer). company: type: string first_name: @@ -217,7 +219,7 @@ paths: tags: - Customers summary: Delete Customers - description: 'By default, it deletes all *Customers*. Up to 100 customers per batch can be deleted. ' + description: By default, it deletes all *Customers*. Up to 100 customers per batch can be deleted. operationId: deleteAllCustomers responses: '204': @@ -273,6 +275,7 @@ paths: summary: Update a Customer description: |- Updates a *Customer*. + **Read Only Fields** * id * date_created @@ -280,21 +283,25 @@ paths: * accepts_marketing * addresses * form_fields + ## Notes The `_authentication` object exposes functionality associated with the customer’s ability to log in to the store. All properties of the `_authentication` object are optional. When the `_authentication` object is not supplied with an update request, then the existing customer password remains the same. ## Updating Passwords To manually update a customer password in the same way as the control panel, supply a value for the `password` field: - ``` + + ```js showLineNumbers copy { "_authentication": { "password": "12w69Y217PYR96J" } } + ``` + #### Confirming Passwords An additional optional `password_confirmation` field can also be sent, providing password confirmation as a service: - ``` + ```js showLineNumbers copy { "_authentication": { "password": "12w69Y217PYR96J" @@ -304,7 +311,7 @@ paths: ``` #### Forcing Password Resets To force a customer to reset their password upon their next login attempt, give the `force_reset` field a value of true, as shown here: - ``` + ```js showLineNumbers copy { "_authentication": { "force_reset": true @@ -338,7 +345,7 @@ paths: type: string password_confirmation: type: string - description: 'Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.' + description: Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation. company: type: string description: The name of the company for which the customer works. @@ -368,7 +375,7 @@ paths: Date on which the customer updated their details in the storefront or was updated in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. store_credit: type: string - description: 'The amount of credit the customer has. (Float, Float as String, Integer)' + description: The amount of credit the customer has. (Float, Float as String, Integer) example: '0' registration_ip_address: type: string @@ -383,10 +390,10 @@ paths: description: Store-owner notes on the customer. tax_exempt_category: type: string - description: 'If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. ' + description: If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. accepts_marketing: type: boolean - description: 'If the customer accepts product review emails or abandon cart emails. Read-Only. ' + description: Describes whether the customer accepts product review emails and abandon cart emails. Read-Only. readOnly: true example: true addresses: @@ -410,11 +417,11 @@ paths: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. example: 123BAF reset_pass_on_login: type: boolean @@ -448,7 +455,7 @@ paths: tags: - Customers summary: Get a Count of Customers - description: 'Returns a count of all *Customers*. ' + description: Returns a count of all *Customers*. operationId: getACountOfCustomers responses: '200': @@ -497,16 +504,16 @@ paths: description: |- **This endpoint has special rate limiting protections to protect against abuse.** - Provided a password, will return a true/false response indicating if the provided password matches the customer’s current password. This endpoint is useful if you want to power the login of another system using BigCommerce’s stored customer accounts, or as a safe way to migrate passwords to another system (by checking them against BigCommerce’s password, and if correct, storing it in another system securely.)If the password matches what’s stored against the customer account, the response will be: + Provided a password, will return a true/false response indicating if the provided password matches the customer’s current password. This endpoint is useful if you want to power the login of another system using BigCommerce’s stored customer accounts, or as a safe way to migrate passwords to another system (by checking them against BigCommerce’s password, and if correct, storing it in another system securely.) If the password matches what’s stored against the customer account, the response will be: - ```json + ```js showLineNumbers copy { "success": "true" } ``` If the password does NOT match, the response will instead be: - ```json + ```js showLineNumbers copy { "success": "false" } @@ -550,14 +557,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -618,14 +625,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -649,14 +656,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -675,6 +682,7 @@ paths: summary: Update a Customer Address description: |- Updates a *Customer Address*. + **Read Only Fields** * id * country_iso2 @@ -719,11 +727,11 @@ paths: example: BigCommerce street_1: type: string - description: 'The customer’s street address, line 1.' + description: The customer’s street address, line 1. example: 123 Main Street street_2: type: string - description: 'The customer’s street address, line 2.' + description: The customer’s street address, line 2. city: type: string description: The customer’s city/town/suburb. @@ -803,14 +811,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -832,36 +840,80 @@ paths: tags: - Customer Groups summary: Get All Customer Groups - description: 'Returns a list of *Customer Groups*. Default sorting is by customer-group id, from lowest to highest.' + description: |- + Returns a list of *Customer Groups*. Default sorting is by customer-group ID, from lowest to highest. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: getAllCustomerGroups parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: name in: query - description: 'Filter customer groups by exact name match. Can use `name:like` to filter using a fuzzy matching method. This is good for implementing search.' + description: Filter customer groups by exact name match. schema: type: string + - name: 'name:like' + in: query + description: Filter customer groups by name, using a fuzzy matching method. + schema: + type: string - name: is_default in: query - description: Whether customers who sign up are added to this group by default. + description: Filter by customers who sign up are added to this group by default. schema: type: boolean + - name: date_created + in: query + description: Filter customer groups by date_created. `date_created=2018-09-05T13:43:54` + schema: + type: string + format: date-time + - name: 'date_created:max' + in: query + description: Filter customer groups by maximum date_created. `date_created:max=2018-09-10` + schema: + type: string + - name: 'date_created:min' + in: query + description: Filter customer groups by date_created. `date_created:min=2018-09-05` + schema: + type: string + format: date-time + - name: date_modified + in: query + description: Filter customer groups by date_modified. `date_modified=2018-09-05T13:45:03` + schema: + type: string + format: date-time + - name: '`date_modified:min`' + in: query + description: Filter customer groups by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04` + schema: + type: string + format: date-time + - name: '`date_modified:max`' + in: query + description: Filter customer groups by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04` + schema: + type: string + format: date-time - name: is_group_for_guests in: query - description: If the groups is for guests. There can only be one customer group for guests at a time. + description: Filter whether the group is for guests. There can only be one customer group for guests at a time. schema: type: boolean responses: @@ -879,8 +931,12 @@ paths: summary: Create a Customer Group description: |- Creates a *Customer Group*. + **Required Fields** * name + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: createACustomerGroup parameters: - $ref: '#/components/parameters/ContentType' @@ -898,7 +954,7 @@ paths: schema: $ref: '#/components/schemas/customerGroup_Full' '207': - description: 'The customer group was created, but the sitewide discount update failed. You may retry the request.' + description: The customer group was created, but the sitewide discount update failed. You may retry the request. content: application/json: schema: @@ -935,23 +991,57 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: name in: query - description: Name of the customer groups + description: Name of the customer groups. + schema: + type: string + - name: date_created + in: query + description: 'Filter items by date_created. `date_created=2018-09-05T13:43:54`' + schema: + type: string + format: date-time + - name: 'date_created:max' + in: query + description: 'Filter items by maximum date_created. `date_created:max=2018-09-10`' + schema: + type: string + - name: 'date_created:min' + in: query + description: 'Filter items by date_created. `date_created:min=2018-09-05`' schema: type: string + format: date-time + - name: date_modified + in: query + description: 'Filter items by date_modified. `date_modified=2018-09-05T13:45:03`' + schema: + type: string + format: date-time + - name: 'date_modified:min' + in: query + description: 'Filter items by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04`' + schema: + type: string + - name: 'date_modified:max' + in: query + description: 'Filter items by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04`' + schema: + type: string + format: date-time - name: is_default in: query description: Whether customers who sign up are added to this group by default. @@ -998,7 +1088,7 @@ paths: schema: $ref: '#/components/schemas/customerGroup_Full' '207': - description: 'The customer group was updated, but the sitewide discount update failed. You may retry the request.' + description: The customer group was updated, but the sitewide discount update failed. You may retry the request. content: application/json: schema: @@ -1020,8 +1110,10 @@ paths: summary: Delete a Customer Group description: |- Deletes a *Customer Group*. + **Notes** - All existing customers are unassigned from the group when it is deleted. + - All existing customers are unassigned from the group when it is deleted. + - The default rate limit for this endpoint is 40 concurrent requests. operationId: deleteACustomerGroup responses: '204': @@ -1041,7 +1133,7 @@ paths: tags: - Customer Groups summary: Get a Count of Customer Groups - description: 'Returns a count of all *Customer Groups*. ' + description: Returns a count of all *Customer Groups*. operationId: getACountOfCustomerGroups responses: '200': @@ -1112,11 +1204,11 @@ components: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. example: 123BAF x-internal: false customerFormFields: @@ -1125,11 +1217,11 @@ components: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. example: 123BAF x-internal: false shippingAddress_Full: @@ -1138,7 +1230,7 @@ components: properties: url: type: string - description: URL of the shipping address for api requests + description: URL of the shipping address for API requests. example: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/129/shippingaddresses' resource: type: string @@ -1221,11 +1313,11 @@ components: properties: id: type: integer - description: Id of the customer group - example: 1 + description: ID of the customer group. + example: 1 name: type: string - description: Name of the group + description: Name of the group. example: Wholesale is_default: type: boolean @@ -1235,7 +1327,7 @@ components: $ref: '#/components/schemas/categoryAccessLevel_Full' discount_rules: type: array - description: A collection of discount rules that are automatically applied to customers who are members of the group + description: A collection of discount rules that are automatically applied to customers who are members of the group. items: type: object properties: @@ -1254,16 +1346,24 @@ components: - price amount: type: string - description: A float that specifies the value applied to the price modified - example: '"5.0000" (Float, Float as String, Integer)' + description: A float that specifies the value applied to the price modified. (Float, Float as String, Integer) + example: '"5.0000"' price_list_id: type: integer - description: 'If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned.' + description: If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned. example: 3 + date_created: + type: string + description: Date on which the customer group was created. + example: 2023-07-17 06:30:41 + date_modified: + type: string + description: Date on which the customer group was last modified. + example: 2023-07-25 01:15:19 is_group_for_guests: type: boolean - description: If the groups is for guests. There can only be one customer group for guests at a time. - description: 'When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [Control Panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing) this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior via API.' + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. + description: When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [store control panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing), this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API. x-internal: false country_Full: title: country_Full @@ -1271,7 +1371,7 @@ components: properties: id: type: integer - description: Id of the country. + description: ID of the country. example: 13 country: type: string @@ -1346,7 +1446,7 @@ components: properties: name: type: string - description: Name of the group + description: Name of the group. example: Wholesale is_default: type: boolean @@ -1356,7 +1456,7 @@ components: $ref: '#/components/schemas/categoryAccessLevel_Full' discount_rules: type: array - description: A collection of discount rules that are automatically applied to customers who are members of the group + description: A collection of discount rules that are automatically applied to customers who are members of the group. items: type: object properties: @@ -1375,23 +1475,31 @@ components: - price amount: type: string - description: A float that specifies the value applied to the price modified - example: '"5.0000" (Float, Float as String, Integer)' + description: A float that specifies the value applied to the price modified. (Float, Float as String, Integer) + example: '"5.0000"' price_list_id: type: integer - description: 'If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned.' + description: If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned. example: 3 + date_created: + type: string + description: Date on which the customer group was created. + example: 2023-07-17 06:30:41 + date_modified: + type: string + description: Date on which the customer group was last modified. + example: 2023-07-25 01:15:19 is_group_for_guests: type: boolean - description: If the groups is for guests. There can only be one customer group for guests at a time. - description: 'When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [Control Panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing) this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior via API.' + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. + description: When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [store control panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing), this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API. x-internal: false validatePassword: type: object properties: success: type: boolean - description: Will return `true` or `false` + description: Will return `true` or `false`. x-internal: false customer_Base: title: customer_Base @@ -1400,7 +1508,7 @@ components: properties: _authentication: type: object - description: 'Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.' + description: Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation. properties: force_reset: type: boolean @@ -1430,7 +1538,7 @@ components: example: '1234567890' store_credit: type: string - description: 'The amount of credit the customer has. (Float, Float as String, Integer)' + description: The amount of credit the customer has. (Float, Float as String, Integer) example: '0' registration_ip_address: type: string @@ -1446,10 +1554,10 @@ components: tax_exempt_category: type: string - description: 'If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.' + description: If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. accepts_marketing: type: boolean - description: 'If the customer accepts product review emails or abandon cart emails. Read-Only. ' + description: Describes whether the customer accepts product review emails or abandon cart emails. Read-Only. example: true readOnly: true addresses: @@ -1474,11 +1582,11 @@ components: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. nullable: true reset_pass_on_login: type: boolean @@ -1619,7 +1727,7 @@ components: is_group_for_guests: name: is_group_for_guests in: query - description: If the groups is for guests. There can only be one customer group for guests at a time. + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. schema: type: boolean securitySchemes: @@ -1637,15 +1745,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/customers.v3.yml b/reference/customers.v3.yml index 002557f95..7362cdd31 100644 --- a/reference/customers.v3.yml +++ b/reference/customers.v3.yml @@ -6,7 +6,7 @@ info: Create and manage customers. ## Resources - * [Customer and Subscribers Overview](/api-docs/store-management/customers). + * [Customer and Subscribers Overview](/docs/store-operations/customers/customers-subscribers-overview). termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -171,13 +171,18 @@ paths: * `segment_ids`- segments the customer belongs to (Beta) `include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids` + explode: false schema: - type: string - enum: - - addresses - - storecredit - - attributes - - formfields + type: array + items: + type: string + enum: + - addresses + - storecredit + - attributes + - formfields + - shopper_profile_id + - segment_ids - in: query name: sort description: 'Sort items by date_created, date_modified, or last_name:* `date_created:asc` - date created, ascending* `date_created:desc` - date created, descending* `last_name:asc` - last name, ascending* `last_name:desc` - last name, descending * `date_modified:asc` - date modified, ascending* `date_modified:desc`- date modified, descending Example: `sort=last_name:asc`' @@ -213,9 +218,6 @@ paths: * Attributes must be [created](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute) **BEFORE** creating a customer. * attribute_id * attribute_value -- This is input as a string, regardless of the [Type](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute). - - **Limits** - * Limit of 10 concurrent requests **Notes** @@ -347,22 +349,11 @@ paths: last_name: string company: string phone: string + registration_ip_address: string notes: string tax_exempt_category: string customer_group_id: 0 id: 1 - addresses: - - address1: string - address2: string - address_type: string - city: string - company: string - country_code: string - first_name: string - last_name: string - phone: string - postal_code: string - state_or_province: string authentication: force_password_reset: true new_password: string123 @@ -520,6 +511,7 @@ paths: * **state_or_province** * **postal_code** * An attempt to create an address that already exists will result in no change to the address or custom form field values, an HTTP 200 return code, and the address will be absent from the response body. + * The default rate limit for this endpoint is 10 concurrent requests. summary: Create a Customer Address operationId: CustomersAddressesPost deprecated: false @@ -1483,8 +1475,6 @@ paths: - Customer Consent operationId: CustomersConsentByCustomerId_GET deprecated: false - parameters: - - $ref: '#/components/parameters/customerId' responses: '200': $ref: '#/components/responses/consent_Resp' @@ -1521,7 +1511,6 @@ paths: schema: type: string default: application/json - - $ref: '#/components/parameters/customerId' requestBody: content: application/json: @@ -1554,11 +1543,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' parameters: - - schema: - type: string - name: customerId - in: path - required: true + - $ref: '#/components/parameters/customerId' '/customers/{customerId}/stored-instruments': get: summary: Get Stored Instruments @@ -2508,15 +2493,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/email_templates.v3.yml b/reference/email_templates.v3.yml index a1d216c8a..95b83b424 100644 --- a/reference/email_templates.v3.yml +++ b/reference/email_templates.v3.yml @@ -341,15 +341,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/form_fields.sf.yml b/reference/form_fields.sf.yml index 674a97cbb..b0eef355b 100644 --- a/reference/form_fields.sf.yml +++ b/reference/form_fields.sf.yml @@ -4,9 +4,9 @@ info: description: |- Read form fields on a BigCommerce hosted storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). > #### Warning > Breaking changes may be introduced to this endpoint while in beta. @@ -79,13 +79,13 @@ components: description: Field name custom: type: boolean - description: Wether is a custom field or system built-in field. + description: Whether this is a custom field or system built-in field. label: type: string description: User-friendly label required: type: boolean - description: Wether this field is required or not + description: Whether this field is required or not default: type: string description: The field unique ID diff --git a/reference/geography.v2.yml b/reference/geography.v2.yml index cb1555689..64cf350a9 100644 --- a/reference/geography.v2.yml +++ b/reference/geography.v2.yml @@ -8,6 +8,7 @@ info: paths: '/countries': get: + operationId: get-all-countries description: 'Get a list of all countries available. A country or territory, identifiable by an ISO 3166 country code.' summary: Get All Countries parameters: @@ -60,6 +61,7 @@ paths: - Countries '/countries/{id}': get: + operationId: get-a-country description: 'Returns a single *Country*. Gets a country. A country or territory, identifiable by an ISO 3166 country code.' summary: Get a Country parameters: @@ -99,6 +101,7 @@ paths: '/countries/{country_id}/states': get: + operationId: get-all-country-states description: |- Returns a list of *States* belonging to a *Country*. A state or province, identifiable by an ISO 3166 subdivision code. @@ -166,6 +169,7 @@ paths: '/countries/{country_id}/states/{id}': get: + operationId: get-a-state description: |- Returns a *State*. A state or province, identifiable by an ISO 3166 subdivision code. @@ -232,10 +236,11 @@ paths: summary: Get a Count of All Countries tags: - Countries - operationId: countriesCount + operationId: get-count-countries description: Returns a count of all countries. '/countries/states/count': get: + operationId: get-count-states responses: '200': $ref: '#/components/responses/countResponse' @@ -245,6 +250,7 @@ paths: description: Returns a count of all states. '/countries/states': get: + operationId: get-all-states responses: '200': $ref: '#/components/responses/countriesStatesCollectionResponse' @@ -265,10 +271,11 @@ paths: description: The ordered grouping of results to return. '/countries/{country_id}/states/count': get: + operationId: get-count-country-states responses: '200': $ref: '#/components/responses/countResponse' - summary: 'Get a Count of Country’s States ' + summary: 'Get a Count of Country’s States' tags: - States description: Returns a count of a country's states. @@ -372,15 +379,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/marketing.v2.yml b/reference/marketing.v2.yml index 0891c25c8..47a422434 100644 --- a/reference/marketing.v2.yml +++ b/reference/marketing.v2.yml @@ -637,7 +637,7 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -679,7 +679,7 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -766,7 +766,7 @@ paths: balance: "500.0000" to_name: Alyss order_id: 1281 - template: "Celebration" + template: "celebration.html" message: "Celebrate" to_email: test@test.com from_name: Noland @@ -782,7 +782,7 @@ paths: balance: "700.0000" to_name: Alyss order_id: 0 - template: "General" + template: "general.html" message: "Test" to_email: test@test.com from_name: Noland @@ -798,7 +798,7 @@ paths: balance: "50.0000" to_name: Lyss order_id: 0 - template: "Celebration" + template: "celebration.html" message: "Celebrate" to_email: test5@test.com from_name: Somethingelse @@ -857,7 +857,7 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -1012,13 +1012,11 @@ components: properties: countries: type: string - ? - : type: string shipping_methods: type: array description: This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping - methods are enabled, please use the [List Shipping Methods](/api/v2#list-shipping-methods) + methods are enabled, please use the [List Shipping Methods](/archive/store-operations/v2-catalog-products/v2-products#list-shipping-methods) endpoint. items: type: string @@ -1193,14 +1191,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Girl - - Boy - - Celebration - - Christmas - - General + - birthday.html + - girl.html + - boy.html + - celebration.html + - christmas.html + - general.html message: type: string description: Text that will be sent to the recipient, such as “Congratulations.” @@ -1255,14 +1253,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Boy - - Girl - - Celebration - - Christmas - - General + - birthday.html + - boy.html + - girl.html + - celebration.html + - christmas.html + - general.html message: type: string description: Text that will be sent to the recipient, such as “Congratulations.” @@ -1318,14 +1316,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Boy - - Girl - - Celebration - - Christmas - - General + - birthday.html + - boy.html + - girl.html + - celebration.html + - christmas.html + - general.html message: maxLength: 250 type: string @@ -1504,7 +1502,7 @@ components: balance: "500.0000" to_name: Alyss order_id: 1281 - template: "Girl" + template: "girl.html" to_email: test@test.com from_name: Noland from_email: test1@test.com @@ -1518,7 +1516,7 @@ components: balance: "700.0000" to_name: Alyss order_id: 0 - template: "Boy" + template: "boy.html" to_email: test@test.com from_name: Noland from_email: test1@test.com @@ -1532,7 +1530,7 @@ components: balance: "50.0000" to_name: Lyss order_id: 0 - template: "Christmas" + template: "christmas.html" to_email: test5@test.com from_name: Somethingelse from_email: test15@test.com @@ -1557,7 +1555,7 @@ components: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -1576,15 +1574,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/orders.sf.yml b/reference/orders.sf.yml index 2f9f7c455..99f339cae 100644 --- a/reference/orders.sf.yml +++ b/reference/orders.sf.yml @@ -4,9 +4,9 @@ info: description: |- Get order data immediately after an order is placed on the storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -44,6 +44,22 @@ paths: exclusiveMinimum: false type: integer format: int32 + - name: include + in: query + description: Sub-resources to include in an Order, in a comma-separated list. The ID and the specified fields will be returned. + explode: false + schema: + type: array + items: + type: string + enum: + - lineItems + - billingAddress + - coupons + - currency + - taxes + - payments + - consignments responses: '200': description: '' @@ -261,6 +277,9 @@ components: type: number description: Quantity of this item. format: double + brand: + type: string + description: The product's brand. isTaxable: type: boolean description: Whether the item is taxable. @@ -297,7 +316,7 @@ components: format: double type: type: string - description: the product type - physical or digital + description: the product type - physical or digital. addedByPromotion: type: boolean description: Whether this item has been added automatically by a promotion. @@ -360,6 +379,9 @@ components: type: number description: Quantity of this item. format: double + brand: + type: string + description: The item's brand. isTaxable: type: boolean description: Whether the item is taxable. @@ -672,6 +694,9 @@ components: properties: {} discountAmount: type: integer + brand: + type: string + description: The product's brand. listPrice: type: number salePrice: diff --git a/reference/orders.v2.oas2.yml b/reference/orders.v2.oas2.yml index 5160277c9..22bdc2e3a 100644 --- a/reference/orders.v2.oas2.yml +++ b/reference/orders.v2.oas2.yml @@ -7,7 +7,7 @@ info: ## Order - The Order object contains a record of the purchase agreement between a shopper and a merchant. To learn more about creating orders, see [Orders API Guide](/api-docs/orders/orders-api-overview). + The Order object contains a record of the purchase agreement between a shopper and a merchant. To learn more about creating orders, see [Orders API Guide](/docs/store-operations/orders). ### Currency Fields @@ -72,11 +72,11 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/order_id_path' get: - description: Gets an *Order*. To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview). + description: Gets an *Order*. To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). summary: Get an Order tags: - Orders - parameters: + parameters: - $ref: '#/components/parameters/order_includes' responses: '200': @@ -97,7 +97,7 @@ paths: To remove a product from an order, set that product’s `quantity` to `0`. - To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview). + To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). summary: Update an Order tags: - Orders @@ -156,8 +156,8 @@ paths: - product_id: 123 quantity: 5 product_options: - id: 56 - value: 12 + - id: 56 + value: 12 price_inc_tax: 12.45 price_ex_tax: 10.12 Adding a new product to order: @@ -175,8 +175,8 @@ paths: product_id: 123 quantity: 1 product_options: - id: 56 - value: 12 + - id: 56 + value: 12 price_inc_tax: 12.45 price_ex_tax: 10.12 required: true @@ -214,7 +214,9 @@ paths: **Notes** - The default sort is by order id, from lowest to highest. + * The default sort is by order id, from lowest to highest. + * By default, requests sent without parameters will only return 50 orders. + tags: - Orders parameters: @@ -244,7 +246,7 @@ paths: operationId: getAllOrders post: description: |- - Creates an *Order*. To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview). + Creates an *Order*. To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). Create an order with an existing catalog product or a custom product. @@ -282,20 +284,20 @@ paths: value: status_id: 0 customer_id: 1 - billing_address: + billing_address: first_name: Jane last_name: Doe street_1: 123 Main Street city: Austin state: Texas - zip: 78751 + zip: '78751' country: United States country_iso2: US email: janedoe@example.com - products: - - product_id: 118, - quantity: 1, - variant_id: 93 + products: + - product_id: 118 + quantity: 1 + variant_id: 93 Custom Product: value: status_id: 0 @@ -610,17 +612,23 @@ paths: operationId: getAllOrderShipments post: description: | - Creates an *Order Shipment*. For more details, see [Shipping an Order](/api-docs/orders/orders-api-overview#creating-order-shipments). + Creates an *Order Shipment*. For more details, see [Shipping an Order](/docs/store-operations/orders#creating-order-shipments). **Required Fields** * order_address_id * items **Usage notes** + + There are three methods for generating a tracking link for a shipment: + + 1. Use `shipping_provider` and `tracking_number`: This generates an automatic tracking link that you can click from the BigCommerce control panel and customer-facing emails. The `generated_tracking_link` property in the API response represents this tracking link. The `tracking_link` property in the API response will remain empty. + + 2. Use `tracking_carrier` and `tracking_number`: This also creates an automatic tracking link that you can click in both the BigCommerce control panel and customer-facing emails. Like the previous method, the `generated_tracking_link` property in the API response represents this tracking link. The `tracking_link` property in the API response will remain empty. + + 3. Supply a custom `tracking_link`: By providing a value for the `tracking_link` property, you can use your own tracking link within the BigCommerce control panel and in customer-facing emails. The API response will return your supplied tracking link as part of the `tracking_link` property in the response. In situations when there isn't a `generated_tracking_link`, the property in the API response will remain empty. - Presuming that a valid carrier code is used, a tracking link is generated if either `shipping_provider` or `tracking_carrier` is supplied alongside a tracking number. Providing only the tracking number will result in non-clickable text in the customer facing email. - - Acceptable values for `shipping_provider` include an empty string (`""`), auspost, canadapost, endicia, usps, fedex, royalmail, ups, upsready, upsonline, or shipperhq. + Acceptable values for `shipping_provider` include an empty string (`""`), `auspost`, `carrier_{your_carrier_id}` (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)), `canadapost`, `endicia`, `usps`, `fedex`, `royalmail`, `ups`, `upsready`, `upsonline`, or `shipperhq`. Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). summary: Create Order Shipment @@ -690,7 +698,7 @@ paths: value: tracking_number: EJ958083578US order_address_id: 1 - shipping_provider: '' + shipping_provider: fedex items: - order_product_id: 15 quantity: 2 @@ -908,7 +916,7 @@ paths: description: |- * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. schema: - type: string + type: string enum: - consignments.line_items get: @@ -984,22 +992,22 @@ paths: timestamp: 'Fri, 24 Jun 2022 03:52:03 +0000' shipping_provider_id: bcrealtime shipping_provider_quote: - rate: - value: '107.32' - unit: USD - transitTime: '1' - name: Priority Overnight - signatureConfirmationFee: {} - carrierName: '' - carrierCode: {} - code: {} - deliveryMessage: '' - labelSizes: [] - insuredMailFee: {} - dates: [] - rateId: {} - description: '' - additionalInfo: {} + - rate: + value: '107.32' + unit: USD + transitTime: '1' + name: Priority Overnight + signatureConfirmationFee: {} + carrierName: '' + carrierCode: {} + code: {} + deliveryMessage: '' + labelSizes: [] + insuredMailFee: {} + dates: [] + rateId: {} + description: '' + additionalInfo: {} provider_code: fedex carrier_code: '' rate_code: '' @@ -1238,12 +1246,13 @@ components: in: query description: |- * `consignments` - include the response returned from the request to the `/orders/{order_id}/consignments` endpoint. - * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. This implies `include=consignments`. + + * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. This implies `include=consignments`. schema: - type: string + type: string enum: - consignments - - consignments.line_items + - consignments.line_items responses: orderStatusCollection_Resp: description: Get All Order Status Collection Response. @@ -1455,7 +1464,7 @@ components: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/100/coupons' resource: /orders/100/coupons external_id: null - external_merchant_id: {} + external_merchant_id: null tax_provider_id: BasicTaxProvider store_default_currency_code: '' store_default_to_transactional_exchange_rate: '1.0000000000' @@ -1649,10 +1658,10 @@ components: street_2: '' city: Austin state: Texas - zip: 78108 + zip: '78108' country: United States country_iso2: US - phone: 1234567890 + phone: '1234567890' email: janedoe@example.com form_fields: - name: Delivery Instructions @@ -1688,51 +1697,51 @@ components: date_shipped: '' status_id: 11 status: Awaiting Fulfillment - subtotal_ex_tax: 924.47 - subtotal_inc_tax: 1000.74 - subtotal_tax: 76.27 - base_shipping_cost: 8 - shipping_cost_ex_tax: 7.39 - shipping_cost_inc_tax: 8 - shipping_cost_tax: 0.61 + subtotal_ex_tax: '924.47' + subtotal_inc_tax: '1000.74' + subtotal_tax: '76.27' + base_shipping_cost: '8' + shipping_cost_ex_tax: '7.39' + shipping_cost_inc_tax: '8' + shipping_cost_tax: '0.61' shipping_cost_tax_class_id: 0 - base_handling_cost: 0 - handling_cost_ex_tax: 0 - handling_cost_inc_tax: 0 - handling_cost_tax: 0 + base_handling_cost: '0' + handling_cost_ex_tax: '0' + handling_cost_inc_tax: '0' + handling_cost_tax: '0' handling_cost_tax_class_id: 0 - base_wrapping_cost: 0 - wrapping_cost_ex_tax: 0 - wrapping_cost_inc_tax: 0 - wrapping_cost_tax: 0 + base_wrapping_cost: '0' + wrapping_cost_ex_tax: '0' + wrapping_cost_inc_tax: '0' + wrapping_cost_tax: '0' wrapping_cost_tax_class_id: 0 - total_ex_tax: 931.86 - total_inc_tax: 1008.74 + total_ex_tax: '931.86' + total_inc_tax: '1008.74' total_tax: 76.88 items_total: 11 items_shipped: 0 payment_method: Test Payment Gateway payment_provider_id: '' payment_status: captured - refunded_amount: 0 + refunded_amount: '0' order_is_digital: false - store_credit_amount: 0 - gift_certificate_amount: 0 + store_credit_amount: '0' + gift_certificate_amount: '0' ip_address: 70.112.53.67 geoip_country: United States geoip_country_iso2: US currency_id: 1 currency_code": USD - currency_exchange_rate: 1 + currency_exchange_rate: '1' default_currency_id: 1 default_currency_code: USD staff_notes: BIN-45 customer_message: Custom Journal Added - discount_amount: 0 + discount_amount: '0' coupon_discount": 0 shipping_address_count: 1 is_deleted: false - ebay_order_id: 0 + ebay_order_id: '0' cart_id: 8b84f622-faf1-4c10-887b-f5dff2f9eaf4 billing_address: first_name: Jane @@ -1748,13 +1757,13 @@ components: phone: '1234567890' email: janedoe@email.com form_fields: - name: Delivery Instructions - value: Leave in backyard + - name: Delivery Instructions + value: Leave in backyard is_email_opt_in: false credit_card_type: {} order_source: manual channel_id: 1 - external_source: {} + external_source: '' products: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/products' resource: /orders/247/products @@ -1764,11 +1773,11 @@ components: coupons: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/coupons' resource: /orders/247/coupons - external_id: {} - external_merchant_id: {} + external_id: null + external_merchant_id: null tax_provider_id: BasicTaxProvider store_default_currency_code: USD - store_default_to_transactional_exchange_rate: 1 + store_default_to_transactional_exchange_rate: '1' custom_status: Awaiting Fulfillment customer_locale: en external_order_id: external-order-id @@ -1841,9 +1850,9 @@ components: total_tax: '9.2400' weight: '1.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -1931,6 +1940,7 @@ components: display_style: Pick list configurable_fields: [] gift_certificate_id: null + discounted_total_inc_tax: '63.6400' - id: 66 order_id: 149 product_id: 86 @@ -1948,9 +1958,9 @@ components: total_tax: '0.0000' weight: '0.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -1979,12 +1989,13 @@ components: product_options: [] configurable_fields: [] gift_certificate_id: null + discounted_total_inc_tax: '0.0000' orderProductLineItem_Resp: description: '' content: application/json: schema: - $ref: '#/components/schemas/orderProducts' + $ref: '#/components/schemas/orderProducts' examples: Product: value: @@ -2008,9 +2019,9 @@ components: total_tax: '5.2800' weight: '2.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2037,9 +2048,10 @@ components: brand: BigCommerce applied_discounts: [] product_options: [] + discounted_total_inc_tax: '37.2300' Product with file upload: value: - - id: 35 + id: 35 order_id: 125 product_id: 127 variant_id: 99 @@ -2063,9 +2075,9 @@ components: height: '0.0000' depth: '0.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2079,7 +2091,7 @@ components: wrapping_message: '' quantity_shipped: 0 event_name: null - event_date: '' + event_date: null fixed_shipping_cost: '0.0000' ebay_item_id: '' ebay_transaction_id: '' @@ -2102,8 +2114,8 @@ components: display_value: BigCommerceLogo.jpeg display_value_customer: BigCommerceLogo.jpeg display_value_merchant: BigCommerceLogo.jpeg - value: {\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"} - type: File upload field + value: "{\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"}" + type: File Upload name: Custom Logo Engraving display_style: "" configurable_fields: [] @@ -2134,9 +2146,9 @@ components: height: '0.0000' depth: '0.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2150,7 +2162,7 @@ components: wrapping_message: '' quantity_shipped: 0 event_name: null - event_date: '' + event_date: null fixed_shipping_cost: '0.0000' ebay_item_id: '' ebay_transaction_id: '' @@ -2191,9 +2203,9 @@ components: height: '3.0000' depth: '3.0000' quantity: 4 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2206,137 +2218,19 @@ components: wrapping_cost_tax: '0.0000' wrapping_message: '' quantity_shipped: 0 - event_name: {} - event_date: '' + event_name: null + event_date: null fixed_shipping_cost: '0.0000' ebay_item_id: '' ebay_transaction_id: '' option_set_id: 68 - parent_order_product_id: {} + parent_order_product_id: null is_bundled_product: false bin_picking_number: '' - external_id: {} + external_id: null fulfillment_source: '' brand: BigCommerce applied_discounts: [] - Product with custom message: - value: - - id: 143 - option_id: 96 - order_product_id: 240 - product_option_id: 242 - display_name: Color - display_name_customer: Color - display_name_merchant: Color - display_value: Red - display_value_customer: Red - display_value_merchant: Red - value: '211' - type: Swatch - name: Color1549572910-201 - display_style: '' - - id: 144 - option_id: 114 - order_product_id: 240 - product_option_id: 263 - display_name: PickList PriceList - display_name_customer: PickList PriceList - display_name_merchant: PickList PriceList - display_value: Able Brewing System - display_value_customer: Able Brewing System - display_value_merchant: Able Brewing System - value: '237' - type: Product Pick List - name: PickList-PriceList1549572910-201 - display_style: Pick list with photos - - id: 145 - option_id: 97 - order_product_id: 240 - product_option_id: 243 - display_name: T-Shirt Size - display_name_customer: T-Shirt Size - display_name_merchant: T-Shirt Size - display_value: Small T-Shirt - display_value_customer: Small T-Shirt - display_value_merchant: Small T-Shirt - value: '214' - type: Multiple choice - name: T-Shirt-Size1545071633-201 - display_style: Rectangle - - id: 146 - option_id: 105 - order_product_id: 240 - product_option_id: 254 - display_name: Custom Message - display_name_customer: Custom Message - display_name_merchant: Custom Message - display_value: BigCommerce - display_value_customer: BigCommerce - display_value_merchant: BigCommerce - value: BigCommerce - type: Text field - name: Custom-Message1549572912-201 - display_style: '' - configurable_fields: - product_options: - value: - - id: 143 - option_id: 96 - order_product_id: 240 - product_option_id: 242 - display_name: Color - display_name_customer: Color - display_name_merchant: Color - display_value: Red - display_value_customer: Red - display_value_merchant: Red - value: '211' - type: Swatch - name: Color1549572910-201 - display_style: '' - - id: 144 - option_id: 114 - order_product_id: 240 - product_option_id: 263 - display_name: PickList PriceList - display_name_customer: PickList PriceList - display_name_merchant: PickList PriceList - display_value: Able Brewing System - display_value_customer: Able Brewing System - display_value_merchant: Able Brewing System - value: '237' - type: Product Pick List - name: PickList-PriceList1549572910-201 - display_style: Pick list with photos - - id: 145 - option_id: 97 - order_product_id: 240 - product_option_id: 243 - display_name: T-Shirt Size - display_name_customer: T-Shirt Size - display_name_merchant: T-Shirt Size - display_value: Small T-Shirt - display_value_customer: Small T-Shirt - display_value_merchant: Small T-Shirt - value: '214' - type: Multiple choice - name: T-Shirt-Size1545071633-201 - display_style: Rectangle - - id: 146 - option_id: 105 - order_product_id: 240 - product_option_id: 254 - display_name: Custom Message - display_name_customer: Custom Message - display_name_merchant: Custom Message - display_value: BigCommerce - display_value_customer: BigCommerce - display_value_merchant: BigCommerce - value: BigCommerce - type: Text field - name: Custom-Message1549572912-201 - display_style: '' - configurable_fields: [] orderShipmentCollection_Resp: description: '' content: @@ -2390,6 +2284,8 @@ components: - order_product_id: 188 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US - id: 7 order_id: 225 customer_id: 11 @@ -2432,6 +2328,8 @@ components: - order_product_id: 189 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US orderShipment_Resp: description: '' content: @@ -2452,6 +2350,7 @@ components: comments: Ready to go... shipping_provider: usps tracking_carrier: '' + tracking_link: '' billing_address: first_name: Jane last_name: Doe @@ -2485,6 +2384,8 @@ components: - order_product_id: 195 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US orderCount_Resp: description: '' content: @@ -2695,437 +2596,6 @@ components: priority: 0 priority_amount: '4.4000' line_amount: '4.4000' - actual-order-response: - description: '' - content: - application/json: - schema: - title: Order - example: - id: 113 - customer_id: 1 - date_created: 'Wed, 17 Jan 2018 20:11:21 +0000' - date_modified: 'Wed, 25 Apr 2018 20:20:25 +0000' - date_shipped: '' - status_id: 7 - status: Awaiting Payment - subtotal_ex_tax: '143.9500' - subtotal_inc_tax: '143.9500' - subtotal_tax: '0.0000' - base_shipping_cost: '0.0000' - shipping_cost_ex_tax: '0.0000' - shipping_cost_inc_tax: '0.0000' - shipping_cost_tax: '0.0000' - shipping_cost_tax_class_id: 2 - base_handling_cost: '0.0000' - handling_cost_ex_tax: '0.0000' - handling_cost_inc_tax: '0.0000' - handling_cost_tax: '0.0000' - handling_cost_tax_class_id: 2 - base_wrapping_cost: '0.0000' - wrapping_cost_ex_tax: '0.0000' - wrapping_cost_inc_tax: '0.0000' - wrapping_cost_tax: '0.0000' - wrapping_cost_tax_class_id: 3 - total_ex_tax: '138.9500' - total_inc_tax: '138.9500' - total_tax: '0.0000' - items_total: 2 - items_shipped: 0 - payment_method: Cash on Delivery - payment_provider_id: null - payment_status: '' - refunded_amount: '0.0000' - order_is_digital: false - store_credit_amount: '0.0000' - gift_certificate_amount: '0.0000' - ip_address: 64.183.182.114 - geoip_country: United States - geoip_country_iso2: US - currency_id: 1 - currency_code: USD - currency_exchange_rate: '1.0000000000' - default_currency_id: 1 - default_currency_code: USD - staff_notes: '' - customer_message: '' - discount_amount: '0.0000' - coupon_discount: '5.0000' - shipping_address_count: 1 - is_deleted: false - ebay_order_id: '0' - cart_id: 1cf3da59-1c90-42a9-82fb-2a954743a390 - billing_address: - first_name: Jane - last_name: Does - company: '' - street_1: 123 MainStreet - street_2: '' - city: Austin - state: Texas - zip: '78751' - country: United States - country_iso2: US - phone: '' - email: jane@example.com - form_fields: [] - is_email_opt_in: false - credit_card_type: null - order_source: www - external_source: null - products: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/products' - resource: /orders/113/products - shipping_addresses: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/shippingaddresses' - resource: /orders/113/shippingaddresses - coupons: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/coupons' - resource: /orders/113/coupons - external_id: null - external_merchant_id: null - custom_status: Awaiting Payment - external_order_id: external-order-id - type: object - properties: - id: - description: The ID of the order, a read-only value. Do not pass in PUT or POST request. - example: 118 - type: integer - customer_id: - description: The ID of the customer placing the order; or 0 if it was a guest order. - example: 6 - type: number - date_created: - type: string - description: The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST request) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000` - date_modified: - type: string - description: A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822 - date_shipped: - type: string - description: A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822 - status_id: - description: The status ID of the order. - example: 11 - type: integer - cart_id: - description: The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a read-only field; do not set or modify its value in a POST or PUT request. - example: a8458391-ef68-4fe5-9ec1-442e6a767364 - type: string - status: - description: The status will include one of the (string, optional) - values defined under Order Statuses. This is a read-only value. Do not attempt to modify or set this value in a POST or PUT request. - example: Awaiting Fulfillment - type: string - custom_status: - description: Contains the same (string, optional) - value as the `custom_label` property of the Order Statuses object. - example: Awaiting Fulfillment - type: string - subtotal_ex_tax: - description: Override value for subtotal excluding tax. If specified, the field `subtotal_inc_tax` is also required. (Float, Float-As-String, Integer) - example: '225.0000' - type: string - subtotal_inc_tax: - description: Override value for subtotal including tax. If specified, the field `subtotal_ex_tax` is also required. (Float, Float-As-String, Integer) - example: '225.0000' - type: string - subtotal_tax: - description: A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - base_shipping_cost: - description: The value of the base shipping cost. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - shipping_cost_ex_tax: - description: The value of shipping cost, excluding tax. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - shipping_cost_inc_tax: - description: The value of shipping cost, including tax. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - shipping_cost_tax: - description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - shipping_cost_tax_class_id: - description: |- - Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.) - example: 2 - type: integer - base_handling_cost: - description: The value of the base handling cost. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - handling_cost_ex_tax: - description: The value of the handling cost, excluding tax. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - handling_cost_inc_tax: - description: The value of the handling cost, including tax. (Float, Float-As-String, Integer) - oneOf: - - type: number - - type: string - handling_cost_tax: - description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - handling_cost_tax_class_id: - description: |- - A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.) - example: 2 - type: integer - base_wrapping_cost: - description: The value of the base wrapping cost. - example: 0 - oneOf: - - type: string - - type: number - wrapping_cost_ex_tax: - description: The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - wrapping_cost_inc_tax: - description: The value of the wrapping cost, including tax. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - wrapping_cost_tax: - description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - wrapping_cost_tax_class_id: - description: |- - A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.) - example: 3 - type: integer - total_ex_tax: - description: Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer) - example: '225.0000' - type: string - total_inc_tax: - description: Override value for the total, including tax. If specified, the field `total_ex_tax` is also required. (Float, Float-As-String, Integer) - example: '225.0000' - type: string - total_tax: - description: A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - items_total: - description: The total number of items in the order. - example: 1 - type: number - items_shipped: - description: The number of items that have been shipped. - example: 0 - type: number - payment_method: - description: The display name of the payment method for this order. - example: Cash on Delivery - type: string - payment_provider_id: - description: The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used). - example: null - type: string - nullable: true - payment_status: - description: A read-only value. Do not attempt to set or modify this value in a POST or PUT request. - type: string - refunded_amount: - description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - order_is_digital: - description: Whether this is an order for digital products. - example: false - type: boolean - store_credit_amount: - description: Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - gift_certificate_amount: - description: A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - ip_address: - description: IP Address of the customer, if known. - example: 12.345.678.910 - type: string - geoip_country: - description: The full name of the country where the customer made the purchase, based on the IP. - example: United States - type: string - geoip_country_iso2: - description: The country where the customer made the purchase, in ISO2 format, based on the IP. - example: US - type: string - currency_id: - description: The display currency ID. May be different from transactional currency. A read-only value. Do not pass in a POST or PUT request. - example: 1 - type: integer - currency_code: - description: The currency code of the display currency used to present prices on the storefront. May be different from transactional currency. A read-only value. Do not pass in a POST or PUT request. - example: USD - type: string - currency_exchange_rate: - description: A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) - example: '1.0000000000' - type: string - default_currency_id: - description: The transactional currency ID. A read-only value. Do not pass in a POST or PUT request. - example: 1 - type: integer - default_currency_code: - description: The currency code of the transactional currency the shopper pays in. A read-only value. Do not pass in a POST or PUT request. - type: string - example: USD - staff_notes: - type: string - description: Any additional notes for staff. - example: Send Saturday - maxLength: 65535 - customer_message: - description: Message that the customer entered (number, optional) -o the `Order Comments` box during checkout. - example: Thank you - type: string - discount_amount: - description: Amount of discount for this transaction. (Float, Float-As-String, Integer) - example: '0.0000' - type: string - coupon_discount: - description: A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) - example: '5.0000' - type: string - shipping_address_count: - type: number - description: The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT request. - is_deleted: - description: Boolean value indicates whether the order was deleted (archived). Set to to true to archive an order. - example: false - type: boolean - is_email_opt_in: - description: Boolean value indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT request. - example: false - type: boolean - credit_card_type: - description: Credit card type - example: 0 - type: integer - nullable: true - ebay_order_id: - description: If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be `0`. - example: '0' - type: string - billing_address: - title: Billing Address - type: object - description: Required to create an order. - properties: - first_name: - description: '' - example: Jane - type: string - last_name: - description: '' - example: Doe - type: string - company: - description: '' - type: string - street_1: - description: '' - example: 123 Main Street - type: string - street_2: - description: '' - type: string - city: - description: '' - example: Austin - type: string - state: - description: '' - example: TX - type: string - zip: - description: '' - example: '12345' - type: number - country: - description: '' - example: United States - type: string - country_iso2: - description: '' - example: US - type: string - phone: - description: '' - type: string - email: - description: '' - example: janedoe@example.com - type: string - form_fields: - description: '' - type: array - items: - title: Form Fields - type: object - description: Read-Only. If you have required address form fields they will need to be set as optional before creating an order with the API. - properties: - name: - description: Name of the form field. - type: string - example: License Id - readOnly: true - value: - description: Value of the form field. - type: string - example: 123BAF - readOnly: true - readOnly: true - order_source: - description: Orders submitted from the store's website will include a `www` value. Orders submitted with the Checkout API will be set to `checkout_api`. - example: www, iPhone, Android, mobile, manual - type: string - external_source: - description: |- - This value identifies an external system that generated the order and submitted it to BigCommerce using the Orders API. - * When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square). - * If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing. - * If you do not provide a value, then it will default to null.. - example: null - nullable: true - type: string - products: - $ref: '#/components/schemas/products_Resource' - shipping_addresses: - $ref: '#/components/schemas/shippingAddresses_Resource' - coupons: - $ref: '#/components/schemas/coupons_Resource' - external_id: - description: ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order. This field can be updated in a POST request, but using a PUT request to update the order will return a 400 error. The field ''external_id'' cannot be written to. Please remove it from your request before trying again. It cannot be overwritten once set. - example: null - type: string - nullable: true - external_merchant_id: - description: ID of the merchant. - example: null - type: string - nullable: true - channel_id: - type: integer - example: 1 - description: Shows where the order originated. The channel_id will default to 1. Read-Only. - tax_provider_id: - type: string - description: | - BasicTaxProvider - Tax is set to manual and order is created in the store. - - AvaTaxProvider - Tax is set to automatic and order is created in the store. Used for Avalara. - - "" (empty string) - The order is created with the API, or the tax provider is unknown. 404_Resp: description: Not Found content: @@ -3159,15 +2629,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -3213,12 +2683,12 @@ components: nullable: true type: string amount: - description: Amount of the discount. This information is returned as in integer. Dollar and percentage discounts will return the same. For example, $3 returns as ''3'' while 5% will return as 5. Check the discount type to see what type of discount is available. - example: 5 - oneOf: + description: Amount of the discount. This information is returned as in integer. Dollar and percentage discounts will return the same. For example, $3 returns as `3` while 5% will return as `5`. Check the discount type to see what type of discount is available. + anyOf: - type: string - type: number - type: integer + example: 5 format: float type: type: integer @@ -3291,7 +2761,7 @@ components: example: '54.0000' type: string price_ex_tax: - description: 'The product’s price excluding tax. (Float, Float-As-String, Integer)' + description: The product’s price excluding tax. (Float, Float-As-String, Integer) example: '54.0000' type: string price_inc_tax: @@ -3309,7 +2779,7 @@ components: example: '0.0000' type: string base_total: - description: |- + description: |- Total base price. (Float, Float-As-String, Integer) **Note**: The `base_total` is affected by the tax options set up in the control panel and is altered on tax-free orders. See more details on how `base_total` is affected by visiting the [Responsive Tax Display Settings](https://support.bigcommerce.com/s/article/Manual-Tax-Setup) overview. If the `base_total` is `$0`, it's due to the store's tax settings. To learn more about tax settings in the control panel, check out this [Tax Settings](https://support.bigcommerce.com/s/article/Tax-Overview?language=en_US#tax-settings) support article. @@ -3327,7 +2797,7 @@ components: description: |- Total tax applied to products. For example, if quantity if 2, base price is 5 and tax rate is 10%. price_tax will be $.50 and total_tax will be $1.00. - + If there is a manual discount applied total_tax is calculated as the following: `(price_ex_tax - discount)*tax_rate=total_tax`. (Float, Float-As-String, Integer) @@ -3336,22 +2806,22 @@ components: quantity: description: Quantity of the product ordered. example: 1 - type: number + type: integer base_cost_price: - description: The product’s cost price. This can be set using the Catalog API. (Float, Float-As-String, Integer) Read Only - example: '0.0000' + description: The product’s cost price. This can be set using the Catalog API. (Float, Float-As-String, Integer) + example: '50.0000' type: string cost_price_inc_tax: description: |- The product’s cost price including tax. (Float, Float-As-String, Integer) - The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only - example: '0.0000' + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' type: string cost_price_ex_tax: description: |- - The products cost price excluding tax. (Float, Float-As-String, Integer) - The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only - example: '0.0000' + The product cost price excluding tax. (Float, Float-As-String, Integer) + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' type: string weight: description: Weight of the product. (Float, Float-As-String, Integer) @@ -3386,6 +2856,7 @@ components: description: Name of gift-wrapping option. example: null type: string + nullable: true base_wrapping_cost: description: The value of the base wrapping cost. (Float, Float-As-String, Integer) example: '0.0000' @@ -3447,6 +2918,14 @@ components: bin_picking_number: description: Bin picking number for the physical product. type: string + external_id: + description: (Read-only) ID of the order in another system. For example, the Amazon order ID if this is an Amazon order. + type: string + nullable: true + readOnly: true + brand: + description: The productʼs brand. + type: string applied_discounts: description: Array of objects containing discounts applied to the product. type: array @@ -3457,10 +2936,6 @@ components: type: array items: $ref: '#/components/schemas/orderProductOptions' - external_id: - description: ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order. This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ''external_id'' cannot be written to. Please remove it from your request before trying again. It cannot be overwritten once set. - type: string - nullable: true upc: type: string maxLength: 255 @@ -3481,6 +2956,15 @@ components: example: 52 description: ID of the associated gift certificate. nullable: true + discounted_total_inc_tax: + type: string + example: '0.0000' + description: |- + Represent the correct total amount of the line item after deducting all the discounts and including the tax. This number can be used for accounting purpose. + + This makes it easier to have the "shopper paid" value for a line item and api user doesn't have to do any calculation to deduct discount on the client side. + + This field includes all types of discounts (automatic, coupon, manual) and therefore if you use this value, you don't need to deduct any more discounts at line item level or order level. orderCount: title: orderCount example: @@ -3579,7 +3063,7 @@ components: example: 1 type: integer order_id: - description: |- + description: |- The unique numeric identifier of the order to which the tax was applied. NOTE: Not included if the store was using the automatic tax feature. example: 129 type: integer @@ -3593,7 +3077,7 @@ components: example: 1 type: integer tax_class_id: - description: |- + description: |- The unique numeric identifier of the tax class object. NOTE: Will be 0 if automatic tax was enabled, or if the default tax class was used. example: 0 type: integer @@ -3674,6 +3158,7 @@ components: enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -3681,7 +3166,7 @@ components: - upsready - upsonline - shipperhq - - ' ' + - '' tracking_carrier: type: string title: Tracking Carrier @@ -3690,7 +3175,7 @@ components: Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). tracking_link: type: string - description: Returns a tracking link from the shipping service. + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. comments: type: string description: Comments the shipper wishes to add. @@ -3713,8 +3198,15 @@ components: type: integer example: 87 quantity: - type: number + type: integer example: 2 + shipping_provider_display_name: + type: string + description: The human-readable name for the `shipping_provider`. + readOnly: true + generated_tracking_link: + type: string + description: The tracking link that is generated using the combination of either the `tracking_number` and `shipping_provider` or `tracking_number` and `tracking_carrier`. This will be empty if the custom `tracking_link` value is provided. x-internal: false orderConsignments_Resource: title: orderConsignments_Resource @@ -3843,7 +3335,7 @@ components: example: S type: string value: - description: For file-upload type, it's a unique string describing the properties of the file upload. For other types, it's the value of the property. + description: For file-upload type, itʼs a unique string describing the properties of the file upload. For other types, itʼs the value of the property. example: "{\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"}" type: string type: @@ -4010,7 +3502,6 @@ components: timestamp: type: string description: Time the order was created in RFC 2822 format. - format: date-time shipping_provider_id: type: string example: bcstatic @@ -4050,6 +3541,11 @@ components: description: Tracking number of the shipment. example: w4se4b6ASFEW4T maxLength: 50 + tracking_link: + type: string + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. + example: https://www.mycustomtrackinglink.com/tracking + maxLength: 500 shipping_method: description: | Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. @@ -4062,6 +3558,7 @@ components: enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -4080,7 +3577,7 @@ components: description: Comments the shipper wishes to add. maxLength: 65535 items: - description: |- + description: |- The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ] type: array items: @@ -4090,7 +3587,7 @@ components: type: integer example: 5 quantity: - type: number + type: integer example: 2 orderShipment_Put: type: object @@ -4116,6 +3613,7 @@ components: enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -4129,6 +3627,11 @@ components: description: |- Tracking carrier for the shipment. Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). + tracking_link: + type: string + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. + example: https://www.mycustomtrackinglink.com/tracking + maxLength: 500 comments: type: string description: Comments the shipper wishes to add. @@ -4220,16 +3723,15 @@ components: example: '0' type: string external_id: - description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the `external_id`. You can update this field using a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. + description: (Read-only) The order ID in another system, such as the Amazon order ID if this is an Amazon order. example: null - oneOf: - - type: string + type: string nullable: true + readOnly: true external_merchant_id: description: The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the `external_merchant_id`. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. example: null - oneOf: - - type: string + type: string nullable: true external_source: description: |- @@ -4260,7 +3762,7 @@ components: type: string description: |- IPv4 Address of the customer, if known. - + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address` value will reset the `ip_address_v6` value and vice versa. example: 12.345.678.910 maxLength: 30 @@ -4268,7 +3770,7 @@ components: type: string description: |- IPv6 Address of the customer, if known. - + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address_v6` value will reset the `ip_address` value and vice versa. example: '2001:db8:3333:4444:5555:6666:7777:8888' maxLength: 39 @@ -4350,7 +3852,7 @@ components: external_order_id: type: string example: external-order-id - description: The external id of the order. + description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you can update this field using a POST or PUT request. total_ex_tax: description: Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' @@ -4489,7 +3991,7 @@ components: example: '0.0000' type: string shipping_cost_tax_class_id: - description: |- + description: |- Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.) example: 2 type: integer @@ -4500,7 +4002,7 @@ components: handling_cost_tax_class_id: description: |- A read-only value. Do not attempt to set or modify this value in a POST or PUT request. - + (NOTE: Value ignored if automatic tax is enabled on the store.) example: 2 type: integer @@ -4510,9 +4012,9 @@ components: type: string wrapping_cost_tax_class_id: description: |- - A read-only value. Do not attempt to set or modify this value in a POST or PUT request. + A read-only value. Do not attempt to set or modify this value in a POST or PUT request. - NOTE: Value ignored if automatic tax is enabled on the store. + NOTE: Value ignored if automatic tax is enabled on the store. example: 3 type: integer payment_status: @@ -4559,11 +4061,11 @@ components: example: EUR type: string store_default_currency_code: - description: The currency code of the store's default currency. + description: The currency code of the storeʼs default currency. example: USD type: string store_default_to_transactional_exchange_rate: - description: The exchange rate between the store's default currency and the transactional currency used in the order. + description: The exchange rate between the storeʼs default currency and the transactional currency used in the order. example: '100.0000000000' type: string coupon_discount: @@ -4578,7 +4080,7 @@ components: example: false type: boolean order_source: - description: Orders submitted from the store's website will include a `www` value. Orders submitted with the Checkout API will be set to `checkout_api`. + description: Orders submitted from the storeʼs website will include a `www` value. Orders submitted with the Checkout API will be set to `checkout_api`. example: www, iPhone, Android, mobile, manual type: string consignments: @@ -4605,10 +4107,10 @@ components: title: Custom product description: |- **Usage notes:** - + To `add` a custom product to an existing order, don't include `id` in the payload. You must provide a non-empty value for at least one of these fields: `name`, `name_customer`, or `name_merchant`. To `update` an order product line, `id` is required. The payload should only contain the fields that need to be updated. You cannot change omitted fields. - + Note the following constraints and default field values: - Empty strings `''` and `null` are invalid for `xxx`, `xxx_customer`, and `xxx_merchant`. - `name` and `name_customer` always hold the same value; updating either `name` or `name_customer` will change the value for both of those fields. @@ -4632,7 +4134,7 @@ components: example: Towel Type 1 description: The product name that is shown to merchant in control panel. quantity: - type: number + type: integer price_ex_tax: type: number price_inc_tax: @@ -4657,7 +4159,7 @@ components: To `add` a product to an existing order, don't include `id` in the payload. When adding a product with variants, `product_options` are required. To `update` an order product line, `id` is required. The payload should only contain the fields that need to be updated. The fields that you omit will not be changed. - + Note the following constraints and default field values: - `xxx` and `xxx_customer` always hold the same value. Updating either `xxx` or `xxx_customer` will change the value of both fields. - If both fields `xxx` and `xxx_customer` are present, they must have same value. @@ -4688,7 +4190,7 @@ components: description: The numeric ID of the product. example: 117 quantity: - type: number + type: integer description: The quantity of product being removed. example: 1 product_options: @@ -4696,20 +4198,19 @@ components: description: List of product variant options and modifiers. `product_options` are required when removing a product with variants and not specifying the `variant_id`, or when products have mandatory modifiers. items: type: object - properties: + properties: cost_price_inc_tax: type: string - description: |- + description: |- The product’s cost price including tax. (Float, Float-As-String, Integer) - The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only. - readOnly: true - example: '0.0000' + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' price_ex_tax: type: string description: |- The products cost price excluding tax. (Float, Float-As-String, Integer) The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only. - readOnly: true + readOnly: true example: '0.0000' orderCatalogProduct_Post: title: orderCatalogProduct_Post @@ -4789,7 +4290,7 @@ components: description: The product option value that is shown to a customer in storefront.`xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. minLength: 1 quantity: - type: number + type: integer price_inc_tax: type: number price_ex_tax: @@ -4846,7 +4347,7 @@ components: example: Towel Type 1 description: The product name that is shown to merchant in control panel. quantity: - type: number + type: integer price_inc_tax: type: number price_ex_tax: @@ -4882,7 +4383,7 @@ components: channel_id: description: Shows where the order originated. The channel_id will default to 1. example: 1 - type: integer + type: integer consignments: $ref: '#/components/schemas/orderConsignment_Put' customer_id: @@ -4895,8 +4396,9 @@ components: description: The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000`. type: string default_currency_code: - description: A read-only field displays the currency code of the [transactional currency](/api-docs/multi-currency/guide/introduction#display-vs-transactional) the shopper uses. + description: A read-only field displays the currency code of the [transactional currency](/docs/store-operations/currencies#display-vs-transactional) the shopper uses. type: string + readOnly: true discount_amount: description: Amount of discount for this transaction. (Float, Float-As-String, Integer) example: '0.0000' @@ -4906,16 +4408,15 @@ components: example: '0' type: string external_id: - description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the `external_id`. You can update this field using a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. + description: (Read-only) The order ID in another system, such as the Amazon Order ID if this is an Amazon order. example: null - oneOf: - - type: string + type: string nullable: true + readOnly: true external_merchant_id: description: The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the `external_merchant_id`. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. example: null - oneOf: - - type: string + type: string nullable: true external_source: description: |- @@ -4946,7 +4447,7 @@ components: type: string description: |- IPv4 Address of the customer, if known. - + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address` value will reset the `ip_address_v6` value and vice versa. example: 12.345.678.910 maxLength: 30 @@ -4954,7 +4455,7 @@ components: type: string description: |- IPv6 Address of the customer, if known. - + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address_v6` value will reset the `ip_address` value and vice versa. example: '2001:db8:3333:4444:5555:6666:7777:8888' maxLength: 39 @@ -4973,13 +4474,12 @@ components: order_is_digital: description: Whether this is an order for digital products. example: false - type: boolean + type: boolean payment_method: type: string description: 'The payment method for this order. Can be one of the following: `Manual`, `Credit Card`, `Cash`,`Test Payment Gateway`, etc.' payment_provider_id: description: The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used). - example: '' oneOf: - type: string - type: number @@ -4991,7 +4491,7 @@ components: - $ref: '#/components/schemas/orderCustomProduct_Put' - $ref: '#/components/schemas/orderRemoveProduct_Put' refunded_amount: - description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) + description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) example: '0.0000' type: string shipping_cost_ex_tax: @@ -5008,12 +4508,14 @@ components: example: Send Saturday maxLength: 65535 shipping_addresses: - allOf: - - type: object - properties: - id: - type: integer - - $ref: '#/components/schemas/shippingAddress_Put' + type: array + items: + allOf: + - type: object + properties: + id: + type: integer + - $ref: '#/components/schemas/shippingAddress_Put' status_id: description: The status ID of the order. type: integer @@ -5043,8 +4545,9 @@ components: description: The customer’s locale. external_order_id: type: string + nullable: true example: external-order-id - description: The external id of the order. + description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you can update this field using a POST or PUT request. total_ex_tax: description: Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' @@ -5268,12 +4771,12 @@ components: description: 2-letter ISO Alpha-2 code for the country. email: type: string - description: Pickup location's email address. + description: Pickup locationʼs email address. maxLength: 255 example: location1@example.com phone: type: string - description: Pickup location's phone number. + description: Pickup locationʼs phone number. maxLength: 125 example: +1 111-111-1111 x-examples: {} diff --git a/reference/orders.v3.yml b/reference/orders.v3.yml index a2436c8bc..bff39ebe4 100644 --- a/reference/orders.v3.yml +++ b/reference/orders.v3.yml @@ -380,7 +380,75 @@ paths: '/orders/payment_actions/refunds': parameters: - $ref: '#/components/parameters/Accept' - '/stores/{store_hash}/v3/orders/payment_actions/refund_quotes': + get: + summary: Get All Refunds + description: |- + Returns a list of refunds ordered by refund ID in ascending order. + + Requires at least one of the following scopes: + * `store_v2_transactions_read_only` + * `store_v2_transactions` + * `store_v2_orders_read_only` + * `store_v2_orders` + operationId: getrefunds + tags: + - Payment Actions + parameters: + - name: 'order_id:in' + in: query + description: Filter by `order_id`. Accepts multiple as comma-separated values. + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:in' + in: query + description: Filter by refund `id`. Accepts multiple as comma-separated values. + style: form + explode: false + schema: + type: array + items: + type: integer + - in: query + name: 'created:min' + description: |- + Filter results so they are later than or equal to provided date. + + + Must be in url-encoded RFC 3339 format. + e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format. + Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00` + schema: + type: string + format: date-time + - in: query + name: 'created:max' + description: |- + Filter results so they are earlier than or equal to provided date. + + Must be in url-encoded RFC 3339 format. + e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format. + Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00` + schema: + type: string + format: date-time + - in: query + name: page + description: Specifies the page number in a limited (paginated) list of items. + schema: + type: integer + - in: query + name: limit + description: Controls the number of items per page in a limited (paginated) list of items. + schema: + type: integer + responses: + '200': + $ref: '#/components/responses/RefundCollection_Resp' + '/orders/payment_actions/refund_quotes': post: summary: Create Refund Quotes - BATCH description: |- @@ -493,87 +561,6 @@ paths: tags: - Payment Actions x-private: true - parameters: - - name: store_hash - in: path - required: true - schema: - type: string - '/stores/{store_hash}/v3/orders/payment_actions/refunds': - get: - summary: Get All Refunds - description: |- - Returns a list of refunds ordered by refund ID in ascending order. - - Requires at least one of the following scopes: - * `store_v2_transactions_read_only` - * `store_v2_transactions` - * `store_v2_orders_read_only` - * `store_v2_orders` - operationId: getrefunds - parameters: - - name: store_hash - in: path - required: true - schema: - type: string - - name: 'order_id:in' - in: query - description: Filter by `order_id`. Accepts multiple as comma-separated values. - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:in' - in: query - description: Filter by refund `id`. Accepts multiple as comma-separated values. - style: form - explode: false - schema: - type: array - items: - type: integer - - in: query - name: 'created:min' - description: |- - Filter results so they are later than or equal to provided date. - - - Must be in url-encoded RFC 3339 format. - e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format. - Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00` - schema: - type: string - format: date-time - - in: query - name: 'created:max' - description: |- - Filter results so they are earlier than or equal to provided date. - - - Must be in url-encoded RFC 3339 format. - e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format. - Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00` - schema: - type: string - format: date-time - - in: query - name: page - description: Specifies the page number in a limited (paginated) list of items. - schema: - type: integer - - in: query - name: limit - description: Controls the number of items per page in a limited (paginated) list of items. - schema: - type: integer - responses: - '200': - $ref: '#/components/responses/RefundCollection_Resp' - tags: - - Payment Actions '/orders/{order_id}/metafields': parameters: - $ref: '#/components/parameters/Accept' @@ -3440,15 +3427,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header examples: diff --git a/reference/pages.v3.yml b/reference/pages.v3.yml index cbb9094ab..853d3354c 100644 --- a/reference/pages.v3.yml +++ b/reference/pages.v3.yml @@ -632,7 +632,7 @@ components: Include a header parameter called `X-Auth-Token` and pass it the `access_token` provided with your store API account or generated with your app's `/auth` callback. - ```http title="Security header example" + ```http filename="Security header example" X-Auth-Token: example_access_token ``` @@ -774,7 +774,7 @@ components: allOf: - properties: data: - type: array + type: object items: $ref: '#/components/schemas/Page' meta: diff --git a/reference/payments/accepted-methods_payments.v3.yml b/reference/payments/accepted-methods_payments.v3.yml index 95e4e43a9..3cb37ccca 100644 --- a/reference/payments/accepted-methods_payments.v3.yml +++ b/reference/payments/accepted-methods_payments.v3.yml @@ -3,22 +3,22 @@ info: version: '' title: Accepted Payment Methods description: | - > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/api-docs/store-management/payments-api-overview). + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). The [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) endpoint returns information about the payment methods each configured payment gateway accepts. This information optimizes your implementation's likelihood of making successful payments requests that return errors solely when payment methods fail, without making API calls to the gateway prior to running the payment. - For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/api-docs/store-management/payments-api-overview#compatible-payment-gateways). + For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). - This endpoint uses the X-Auth-Token header to authenticate. For an X-Auth-Token example request, see the related section in our [Authentication article](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + This endpoint uses the X-Auth-Token header to authenticate. For an X-Auth-Token example request, see the related section in our [Authentication article](/docs/start/authentication#x-auth-token-header-example-requests). > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. ## Resources - * [Payments Overview](/api-docs/store-management/payments-api-overview) - * [Process payments authentication example request](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) - * [Orders Overview](/api-docs/store-management/orders-api-overview) + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) ### Webhooks @@ -482,15 +482,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/payments/access-tokens_payments.v3.yml b/reference/payments/access-tokens_payments.v3.yml index 03e3f6561..25211c673 100644 --- a/reference/payments/access-tokens_payments.v3.yml +++ b/reference/payments/access-tokens_payments.v3.yml @@ -3,23 +3,23 @@ info: version: '' title: Payment Access Token description: | - > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/api-docs/store-management/payments-api-overview). + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). BigCommerce payments requests require a Payment Access Token, or _PAT_, which is a single use BigCommerce-generated JWT that's tied to the particular **order** for which the shopper authorizes BigCommerce to submit a payment. - To get a valid PAT, submit the order number to the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint. Authenticate using an [API account access token](/api-docs/getting-started/api-accounts#api-accounts) with the [Create payments](/api-docs/getting-started/api-accounts#token-creation-scopes) scope as the value of the X-Auth-Token header. + To get a valid PAT, submit the order number to the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint. Authenticate using an [API account access token](/docs/start/authentication/api-accounts#api-accounts) with the [Create payments](/docs/start/authentication/api-accounts#token-creation-scopes) scope as the value of the X-Auth-Token header. - You can also generate a PAT during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout#handling-payments). + You can also generate a PAT during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). - For a guide through the API call sequence needed to create a PAT and make charges, see the [Payments Overview](/api-docs/store-management/payments-api-overview#compatible-payment-gateways). + For a guide through the API call sequence needed to create a PAT and make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. ## Resources - * [Payments Overview](/api-docs/store-management/payments-api-overview) - * [Process payments authentication example request](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) - * [Orders Overview](/api-docs/store-management/orders-api-overview) + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) ### Webhooks @@ -57,7 +57,7 @@ paths: description: |- Use this endpoint to create a payment access token. A payment access token is required to process payments with the BigCommerce API. - You can also generate a payment access token during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout#handling-payments). + You can also generate a payment access token during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). After the token is created, use the token to [Process a payment](/docs/rest-payments/processing#process-payment). @@ -380,15 +380,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/payments/methods_payments.v2.yml b/reference/payments/methods_payments.v2.yml index 5a2b5e66f..614f50ff6 100644 --- a/reference/payments/methods_payments.v2.yml +++ b/reference/payments/methods_payments.v2.yml @@ -2,7 +2,7 @@ openapi: '3.0.1' info: title: Payment Methods (Deprecated) description: | - > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/api-docs/store-management/payments-api-overview). + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). This endpoint is deprecated. Use [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) instead. @@ -12,9 +12,9 @@ info: ## Resources - * [Payments Overview](/api-docs/store-management/payments-api-overview) - * [Process payments authentication example request](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) - * [Orders Overview](/api-docs/store-management/orders-api-overview) + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) ### Webhooks @@ -140,14 +140,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/payments/process_payments.yml b/reference/payments/process_payments.yml index 9573c6e83..30da26157 100644 --- a/reference/payments/process_payments.yml +++ b/reference/payments/process_payments.yml @@ -3,11 +3,11 @@ info: version: '' title: Payment Processing description: | - > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/api-docs/store-management/payments-api-overview). + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). - The Payment Processing API uses BigCommerce's PCI-compliant payments server and a supported payment gateway to charge customers. The payment portal you choose may support charging stored instruments and/or making refund transactions. For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/api-docs/store-management/payments-api-overview#compatible-payment-gateways). + The Payment Processing API uses BigCommerce's PCI-compliant payments server and a supported payment gateway to charge customers. The payment portal you choose may support charging stored instruments and/or making refund transactions. For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). - A Payment Access Token (_PAT_) is required to authorize payment processing requests. The X-Auth-Token header is not required in requests to the payment processing endpoint. To generate a PAT, use the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint or the `completeCheckout` mutation in the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout#handling-payments). For a payment processing authentication example request, see the related section in our [Authentication article](/api-docs/getting-started/authentication#bigcommerce-generated-jwts). + A Payment Access Token (_PAT_) is required to authorize payment processing requests. The X-Auth-Token header is not required in requests to the payment processing endpoint. To generate a PAT, use the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint or the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). For a payment processing authentication example request, see the related section in our [Authentication article](/docs/start/authentication#bigcommerce-generated-jwts). Also note that payment processing requests use the BigCommerce Payments Gateway, which uses a different server than our other REST APIs. Please see the server URL for the payment processing endpoint. @@ -15,9 +15,9 @@ info: ## Resources - * [Payments Overview](/api-docs/store-management/payments-api-overview) - * [Process payments authentication example request](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) - * [Orders Overview](/api-docs/store-management/orders-api-overview) + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) ### Webhooks @@ -55,7 +55,7 @@ paths: tags: - Processing operationId: PaymentsPost - description: 'Process payments for an order. See [Payment Processing](/api-docs/store-management/payments-api-overview) for more information.' + description: 'Process payments for an order. See [Payment Processing](/docs/store-operations/payments) for more information.' parameters: - $ref: '#/components/parameters/AcceptPaymentResponse' - $ref: '#/components/parameters/ContentType' @@ -80,6 +80,7 @@ paths: - $ref: '#/components/schemas/StoredPayPalAccount' - $ref: '#/components/schemas/GiftCertificate' - $ref: '#/components/schemas/StoreCredit' + - $ref: '#/components/schemas/TokenizedCard' payment_method_id: description: Identifier for payment method that will be used for this payment and `id` from the Get Accepted Payment Methods API type: string @@ -133,6 +134,17 @@ paths: instrument: type: store_credit payment_method_id: bigcommerce.store_credit + Tokenized Card: + value: + payment: + instrument: + type: tokenized_card + token: K7KW-M9GX-6PQ3 + iin: 4111111 + last_four_digits: 1111 + expiration_month: 12 + expiration_year: 2030 + payment_method_id: bolt.card required: true x-examples: application/json: @@ -487,6 +499,44 @@ components: x-examples: example-1: type: store_credit + TokenizedCard: + title: Tokenized Card + type: object + x-internal: false + x-examples: + example-1: + type: tokenized_card + token: K7KW-M9GX-6PQ3 + iin: 4111111 + last_four_digits: 1111 + expiration_month: 12 + expiration_year: 2030 + properties: + type: + type: string + description: Type to classify this payment instrument (required). + enum: + - tokenized_card + token: + description: Identifier representing the tokenized card (required). + type: string + minLength: 64 + maxLength: 64 + iin: + type: string + description: Issuer identification number. + last_four_digits: + type: string + description: Last four numbers of this card. + expiration_month: + type: string + description: Expiry month of this card. + expiration_year: + type: string + description: Expiry year of this card. + required: + - type + - token securitySchemes: BearerPAT: description: |- @@ -502,9 +552,9 @@ components: ### Further reading - For an outline of the Process Payment API call flow and more information about authenticating, see [Authentication and Example Requests](/api-docs/getting-started/authentication#bigcommerce-generated-jwts). + For an outline of the Process Payment API call flow and more information about authenticating, see [Authentication and Example Requests](/docs/start/authentication#bigcommerce-generated-jwts). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: http scheme: bearer bearerFormat: 'PAT {{PAYMENT_ACCESS_TOKEN}}' diff --git a/reference/price_lists.v3.yml b/reference/price_lists.v3.yml index 7ae1e06e8..38832d3aa 100644 --- a/reference/price_lists.v3.yml +++ b/reference/price_lists.v3.yml @@ -10,9 +10,9 @@ info: You can create [Price List Assignments](/docs/rest-management/price-lists/price-lists-assignments#create-price-list-assignments) to assign Price Lists to a specific [channel](/docs/rest-management/channels/channel-listings). Price Lists assigned to a channel apply to all shoppers on that channel, unless there are more specific assignments or customer group discounts set up for the shopper's customer group. If an active Price List does not contain prices for a variant, the catalog pricing will be used. - Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil's [handlebars objects](/theme-objects). + Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil's [handlebars objects](/docs/storefront/stencil/themes/context/object-reference/config). - To learn more about Price Lists, see [Price Lists API](/api-docs/store-management/price-list-overview). + To learn more about Price Lists, see [Price Lists API](/docs/store-operations/pricing/price-lists). ## Price Lists Assignments @@ -36,7 +36,7 @@ info: ## Usage notes - You cannot assign Price Lists to a customer group with customer group discounts -- You must delete the customer group discounts first. - - Bulk pricing Tiers may additionally be associated with a price record to indicate different pricing as the quantity in the cart increases. + - Bulk pricing Tiers can additionally be associated with a price record to indicate different pricing as the quantity in the cart increases. - If a variant has a Price Record, any existing product-level bulk pricing will not apply to the cart. For variants without Price Records, any existing product bulk pricing will apply. - [Price Lists Records](/docs/rest-management/price-lists/price-lists-records) accepts bulk upsert. You can only do one bulk upsert at a time. Running more than one bulk upsert in parallel on the **same store** will cause a `429` error and the request will fail. - There are webhooks available for Price Lists assignments. The price list assignment webhook fires when a price list assignment is assigned, reassigned, or unassigned. Note that since Price Lists directly relate to products, neither product nor SKU webhooks are going to fire for corresponding changes, such as pricing. @@ -45,9 +45,9 @@ info: ### Webhooks - * [Price list assignments](/api-docs/channels/guide/webhooks#price-list-assignments) - * [Products](/api-docs/store-management/webhooks/events#products) - * [SKU](/api-docs/store-management/webhooks/events#sku) + * [Price list assignments](/docs/integrations/webhooks/events/channels#price-list-assignments) + * [Products](/docs/integrations/webhooks/events#products) + * [SKU](/docs/integrations/webhooks/events#sku) ### Related endpoints * [Get All Price Lists](/docs/rest-management/price-lists#get-all-price-lists) termsOfService: 'https://www.bigcommerce.com/terms' @@ -770,10 +770,10 @@ paths: put: tags: - Price Lists Records - description: Creates a batch of `Price List Records`; may include price list records from more than one price list. Concurrency limit of 1. + summary: Create Batch of Price Lists Records + description: Creates a batch of `Price Lists Records`; may include price list records from more than one price list. Concurrency limit of 1. operationId: UpsertPriceListRecords requestBody: - description: A BigCommerce `PriceRecord` request. content: application/json: schema: @@ -849,11 +849,14 @@ paths: in: query description: | Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. + explode: false schema: - type: string - enum: - - bulk_pricing_tiers - - sku + type: array + items: + type: string + enum: + - bulk_pricing_tiers + - sku - name: price in: query description: | @@ -1437,13 +1440,6 @@ paths: required: true schema: type: integer - - name: X-Strict-Mode - in: header - description: | - Header that determines whether the Batch API operates in strict mode or not. Strict mode will reject the entire request if any item in the batch has an error. - schema: - type: integer - default: 0 - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -1904,7 +1900,7 @@ paths: description: |- Returns a *Price List Record* using the currency code. You can use optional parameters. **Notes** - * Supports up to 40 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. + * Supports up to 50 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. operationId: getPriceListRecord parameters: - name: price_list_id @@ -1934,11 +1930,14 @@ paths: description: | Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. + explode: false schema: - type: string - enum: - - bulk_pricing_tiers - - sku + type: array + items: + type: string + enum: + - bulk_pricing_tiers + - sku responses: '200': description: '' @@ -2458,7 +2457,10 @@ paths: tags: - Price Lists Records summary: Delete a Price Record by Currency Code - description: Deletes a *Price List Record* using the currency code. + description: |- + Deletes a *Price List Record* using the currency code. + **Note:** + * Supports up to 25 simultaneous DELETE requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. operationId: deletePriceListRecord parameters: - name: price_list_id @@ -2620,7 +2622,10 @@ paths: put: tags: - Price Lists Assignments - description: Upsert a single `Price List Assignment` for a `Price List`. + description: |- + Upsert a single `Price List Assignment` for a `Price List`. + **Note:** + * Supports up to 25 simultaneous PUT requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error and your additional requests will fail. summary: Upsert Price List Assignment operationId: upsertPriceListAssignment parameters: @@ -2787,7 +2792,7 @@ components: description: The price list with which the price record is associated. Either `variant_id` or `sku` is required. sku: type: string - description: The SKU for the variant with which this price record is associated. Either `sku`` or `variant_id is required. + description: The SKU for the variant with which this price record is associated. Either `sku` or `variant_id` is required. currency: type: string description: The 3-letter country code with which this price record is associated. @@ -2864,10 +2869,10 @@ components: description: The Price List with which this price record is associated. variant_id: type: integer - description: The variant with which this price record is associated. Either `variant_id`` or `sku` is required. + description: The variant with which this price record is associated. Either `variant_id` or `sku` is required. sku: type: string - description: The variant with which this price record is associated. Either `sku`` or `variant_id`` is required. + description: The variant with which this price record is associated. Either `sku` or `variant_id` is required. currency: type: string description: The 3-letter currency code with which this price set is associated. @@ -3040,14 +3045,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/pricing.sf.yml b/reference/pricing.sf.yml index 0ad732cb7..4b20d2f21 100644 --- a/reference/pricing.sf.yml +++ b/reference/pricing.sf.yml @@ -45,39 +45,45 @@ paths: properties: channel_id: type: integer - description: The channel context that pricing should be evaluated within. The default BC storefront is channel 1 + description: The channel ID that pricing evaluates within. The default BigCommerce storefront is channel 1. example: 1 currency_code: type: string - description: The currency of prices to be returned for this request + description: The currency code of prices this request returns. + example: USD customer_group_id: type: integer - description: 'The customer group relevant for any customer group pricing, tax values, etc.' + description: The customer group ID that's relevant for any customer group pricing, tax values, etc. items: type: array - description: The items to fetch prices for + description: The items for which to fetch prices. + items: type: object properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array - description: The (optional) option configuration of the product. May be "partially" configured for estimates. + description: The option configuration of the product (optional); might be partially configured for estimates. items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option that is being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option that's being configured. + + **Note:*** This must be the ID, not the value. + description: Details/configuration for the product to request a price for. required: true responses: @@ -96,19 +102,20 @@ paths: properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array - description: The optional product option configuration this price was generated for + description: The optional product option configuration for which this price was generated. + items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option configured for this price + description: The ID of the variant option or modifier option configured for this price. value_id: type: integer description: The selected value ID for the configured option. @@ -117,81 +124,81 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The (optional) RRP/retail price configured for this product. Used for price comparison and storefront display purposes. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The merchant-entered sale price for a product overwrites the default price. The sale_price is optional. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The minimum advertised price (MAP) allowed to be shown on a storefront. A value supplied by the merchant and used for display purposes. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The merchant-entered price for a product could be including or excluding tax. Price must be defined when creating a product and serves as the default price. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: 'The shopper price for a product including modifier, option, and option set rules. Calculated_price may include or exclude estimates for tax.' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The shopper price for a product including modifier, option, and option set rules. The `calculated_price` may include or exclude estimates for tax. price_range: type: object properties: @@ -200,33 +207,33 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. description: The minimum and maximum price that will typically apply to this product. Only used for complex products (products with variants). retail_price_range: type: object @@ -236,33 +243,33 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. description: The productʼs variants that will typically apply to this product. bulk_pricing: type: array @@ -332,6 +339,11 @@ paths: maximum: 1 discount_amount: 1 discount_type: percent + tax_discount_amount: + - as_entered: 10 + tax_inclusive: 10 + tax_exclusive: 10 + entered_inclusive: false meta: {} components: schemas: @@ -340,10 +352,10 @@ components: properties: minimum: type: integer - description: The minumum quantity required to trigger this bulk pricing discount + description: The minimum quantity required to trigger this bulk pricing discount. maximum: type: integer - description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount + description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount. discount_amount: type: number discount_type: @@ -352,6 +364,24 @@ components: - price - percent - fixed + tax_discount_amount: + type: array + description: Formats the `bulk_pricing.discount_amount` into the tax price amounts. + items: + type: object + properties: + as_entered: + type: number + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. + tax_inclusive: + type: number + description: The estimated tax inclusive price for this product based on the provided customer group. + tax_exclusive: + type: number + description: The estimated tax exclusive price for this product based on the provided customer group. + entered_inclusive: + type: boolean + description: Determines whether the 'as_entered' price is inclusive or exclusive of tax based on the store's tax jurisdiction. x-internal: false PricingResponse: type: object @@ -363,10 +393,10 @@ components: properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array description: The optional product option configuration this price was generated for @@ -384,81 +414,81 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The (optional) RRP/retail price configured for this product + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The (optional) RRP/retail price configured for this product. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price_range: type: object properties: @@ -467,34 +497,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. retail_price_range: type: object properties: @@ -503,34 +533,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: For estimated prices, the minimum/maximum price that will typically apply to this product. bulk_pricing: type: array items: @@ -538,18 +568,38 @@ components: properties: minimum: type: integer - description: The minumum quantity required to trigger this bulk pricing discount + description: The minimum quantity required to trigger this bulk pricing discount. maximum: type: integer - description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount + description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount. discount_amount: type: number + description: The price reduction set by the merchant for this bulk pricing discount. discount_type: type: string enum: - price - percent - fixed + description: The format of the price reduction set by the merchant for this bulk pricing discount. + tax_discount_amount: + type: array + description: Formats the `bulk_pricing.discount_amount` into the tax price amounts. + items: + type: object + properties: + as_entered: + type: number + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. + tax_inclusive: + type: number + description: The estimated tax inclusive price for this product based on the provided customer group. + tax_exclusive: + type: number + description: The estimated tax exclusive price for this product based on the provided customer group. + entered_inclusive: + type: boolean + description: Determines whether the 'as_entered' price is inclusive or exclusive of tax based on the store's tax jurisdiction. meta: type: object properties: {} @@ -564,70 +614,71 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. x-internal: false TaxPrice: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. x-internal: false ItemPricing: type: object properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array - description: The optional product option configuration this price was generated for + description: The optional product option configuration for which this price was generated. + items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option configured for this price + description: The ID of the variant option or modifier option configured for this price. value_id: type: integer description: The selected value ID for the configured option. @@ -636,81 +687,81 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The (optional) RRP/retail price configured for this product + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The (optional) RRP/retail price configured for this product. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price_range: type: object properties: @@ -719,34 +770,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax. jurisdiction tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. retail_price_range: type: object properties: @@ -755,34 +806,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. bulk_pricing: type: array items: @@ -793,10 +844,10 @@ components: properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array description: The (optional) option configuration of the product. May be "partially" configured for estimates. @@ -805,10 +856,14 @@ components: properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option being configured. + + **Note:** must be ID, not the value. + description: Details/configuration for the product to request a price for. x-internal: false PricingRequest: @@ -816,27 +871,28 @@ components: properties: channel_id: type: integer - description: The channel context that pricing should be evaluated within. The default BC storefront is channel 1 + description: The channel ID that pricing evaluates within. The default BigCommerce storefront is channel 1. example: 1 currency_code: type: string - description: The currency of prices to be returned for this request + description: The currency of prices to be returned for this request. example: USD customer_group_id: type: integer - description: 'The customer group relevant for any customer group pricing, tax values, etc.' + description: The customer group relevant for any customer group pricing, tax values, etc. items: type: array - description: The items to fetch prices for + description: The items for which to fetch prices. + items: type: object properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array description: The (optional) option configuration of the product. May be "partially" configured for estimates. @@ -845,10 +901,14 @@ components: properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option being configured. + + **Note:** This must be the ID, not the value. + description: Details/configuration for the product to request a price for. x-internal: false securitySchemes: @@ -865,14 +925,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 7d68dca53..f5ae6e6a8 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -20,6 +20,7 @@ security: - X-Auth-Token: [] tags: - name: Redirects + - name: Import-Export paths: '/storefront/redirects': parameters: @@ -28,7 +29,7 @@ paths: tags: - Redirects summary: Get Redirects - description: Returns a collection of the store's 301 redirects across all sites. + description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: GetRedirects parameters: - name: site_id @@ -65,6 +66,7 @@ paths: - from_path - type - site_id + - id - name: direction in: query description: 'Sort direction. Acceptable values are `asc`, `desc`.' @@ -155,6 +157,231 @@ paths: '204': description: No Content content: {} + '/storefront/redirects/imex/jobs': + parameters: + - $ref: '#/components/parameters/Accept' + get: + tags: + - Import-Export + summary: Get Redirect Import-Export Jobs + description: Returns a collection of the storeʼs 301 redirects across all sites. + operationId: getRedirectImportExportJobs + parameters: + - name: id + in: query + description: Filters results by Redirect Import-Export job ID. + style: form + explode: false + schema: + type: string + - name: type + in: query + description: Filters results by the type of the Redirect Import-Export job. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobType' + - name: status + in: query + description: Filters results by the status of the Redirect Import-Export job. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobStatus' + - name: limit + in: query + description: Determines the number of items returned per page. The default is 10 items per page. + schema: + type: integer + default: 10 + - name: page + in: query + description: Specifies the page number to return when the number of items returned exceeds the page limit. Used to paginate large collections. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/301RedirectImportExportJobRead' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + '/storefront/redirects/imex/export': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Import-Export + summary: Create Redirects Export Job + description: Creates a new 301 Redirects export job. + operationId: createRedirectExportJob + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + type: object + properties: + site_id: + type: integer + nullable: true + default: null + description: The site ID for which you wish to export redirects. If no site ID is provided, the request exports all redirects for all sites. + redirect_ids: + type: array + items: + type: integer + default: [] + description: A list of the redirect IDs you wish to export. If no redirect IDs are provided, the request exports all redirects for the given site selection. + include_dynamic_target_urls: + type: boolean + default: false + description: If true, the exported CSV will contain an additional read-only column containing the target URL for dynamic redirects. + description: Data necessary to create a new 301 Redirects export job. + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + '429': + description: Your store already has an active Redirects import or export job running. + '409': + description: No Redirects in your store meet the criteria in your request. + '/storefront/redirects/imex/import': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Import-Export + summary: Create Redirects Import Job + description: Creates a new 301 Redirects import job. + operationId: createRedirectImportJob + parameters: + - $ref: '#/components/parameters/ContentTypeFormData' + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + import_file: + description: |- + A CSV file containing a list of Redirects to be imported. + + The headers must be defined as follows: + + `Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID` + + Not every line will have a value for every column. + type: string + format: binary + example: |- + Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID + store.example.com,/old-path,/new-manual-path,, + store.example.com,/old-product,,Product,12 + store.example.com,/old-brand,,Brand,34 + store.example.com,/old-category,,Category,56 + store.example.com,/old-page,,Page,78 + store.example.com,/old-post,,Post,90 + required: + - import_file + description: Data necessary to create a new 301 Redirects import job. + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + '400': + description: The provided form data was invalid or the file is not a CSV. + '413': + description: The provided file is too large. The maximum file size is 20MB. + '429': + description: Your store already has an active Redirects import or export job running. + '/storefront/redirects/imex/export/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Open Redirect Export Event Stream + description: Opens an event stream to receive live updates from an export job. + operationId: getRedirectExportEvents + responses: + '200': + description: Stream of export events. The `data` attribute is stringified JSON. + content: + text/event-stream: + schema: + type: string + example: 'event: message\ndata: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100}\n\n' + '404': + description: The provided export job ID does not exist. + '/storefront/redirects/imex/import/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Open Redirect Import Event Stream + description: Opens an event stream to receive live updates from an import job. + operationId: getRedirectImportEvents + responses: + '200': + description: Stream of import events. The `data` attribute is stringified JSON. + content: + text/event-stream: + schema: + type: string + example: 'event: message\ndata: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]}\n\n' + '404': + description: The provided import job ID does not exist. + '/storefront/redirects/imex/export/{uuid}/download': + parameters: + - $ref: '#/components/parameters/ContentTypeCsv' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Download Redirect Export + description: Downloads the CSV file containing the results of an export job. + operationId: getRedirectExportDownload + responses: + '200': + description: The exported Redirects in CSV format + content: + text/csv: + schema: + type: string + format: binary + example: | + Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID + store.example.com,/old-path,/redirect-target,, + '404': + description: The requested export download does not exist. components: parameters: Accept: @@ -165,6 +392,14 @@ components: schema: type: string default: 'application/json' + AcceptEventStream: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'text/event-stream' ContentType: name: Content-Type in: header @@ -173,6 +408,30 @@ components: schema: type: string default: 'application/json' + ContentTypeFormData: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'multipart/form-data' + ContentTypeCsv: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'text/csv' + ImportExportIdParam: + name: uuid + description: The import-export job identifier. + in: path + required: true + schema: + type: string + format: uuid schemas: Error: type: object @@ -181,31 +440,26 @@ components: type: integer message: type: string - x-internal: false ErrorResponse400: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse404: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse409: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse422: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false 301RedirectUpsert: required: - from_path @@ -219,12 +473,10 @@ components: type: integer to: $ref: '#/components/schemas/RedirectTo' - description: 'Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data.' - x-internal: false + description: Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data. 301RedirectRead: type: object - description: 'Full detail of a Redirect, optionally including the full destination URL.' - x-internal: false + description: Full detail of a Redirect, optionally including the full destination URL. properties: id: type: integer @@ -240,6 +492,63 @@ components: description: Full destination URL for the redirect. Must be explicitly included via URL parameter. format: uri example: 'https://store-domain.com/new-url' + ImportExportJobType: + type: string + enum: + - import + - export + ImportExportJobStatus: + type: string + enum: + - new + - working + - complete + - aborted + - failed + ImportErrors: + type: array + items: + type: object + description: Detail of an error that occurred during an import job. + properties: + row: + type: integer + description: The row in the import CSV where the error occurred. + message: + type: string + 301RedirectImportExportJobRead: + type: object + description: Full detail of a Redirect Import-Export job. + properties: + id: + type: string + format: uuid + description: The Import-Export job ID. + type: + $ref: '#/components/schemas/ImportExportJobType' + status: + $ref: '#/components/schemas/ImportExportJobStatus' + completed_items: + type: integer + description: The number of items that were successfully imported or exported. + failed_items: + type: integer + description: The number of items that were not successfully imported or exported. + total_items: + type: integer + description: The number of items in the import or export job. + errors: + $ref: '#/components/schemas/ImportErrors' + created_at: + type: string + format: date-time + description: 'The date-time that the import-export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' + completed_at: + type: string + format: date-time + description: 'The date-time that the import-export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' MetaPaginationObject: type: object properties: @@ -275,7 +584,6 @@ components: current: type: string example: '?limit=5&page=1' - x-internal: false RedirectTo: title: RedirectTo type: object @@ -295,13 +603,11 @@ components: maxLength: 2048 type: string example: /new-url/ - x-internal: false DetailedErrors: type: object properties: {} additionalProperties: true title: Detailed Errors - x-internal: false BaseError: type: object properties: @@ -319,7 +625,6 @@ components: type: string description: | Error payload for the BigCommerce API. - x-internal: false ErrorResponse: allOf: - $ref: '#/components/schemas/BaseError' @@ -327,7 +632,6 @@ components: properties: errors: $ref: '#/components/schemas/DetailedErrors' - x-internal: false securitySchemes: X-Auth-Token: name: X-Auth-Token @@ -336,22 +640,22 @@ components: | UI Name | Permission | Parameter | |:--------|:-----------|:----------| - | Content | modify | `store_v2_content` | - | Content | read-only | `store_v2_content_read_only` | + | Content | modify | `store_v2_content` | + | Content | read-only | `store_v2_content_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/scripts.v3.yml b/reference/scripts.v3.yml index 2e2a960f9..2c1795db6 100644 --- a/reference/scripts.v3.yml +++ b/reference/scripts.v3.yml @@ -3,7 +3,7 @@ info: title: Scripts version: '' description: |- - Add client-side code to a BigCommerce storefront page or associate a script with a channel. To learn more about scripts, see the [Scripts API](/api-docs/store-management/scripts) article. + Add client-side code to a BigCommerce storefront page or associate a script with a channel. To learn more about scripts, see the [Scripts API](/docs/integrations/scripts) article. termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -110,6 +110,9 @@ paths: **Read Only Fields** * uuid + **Limits** + * 50 scripts per channel. + **Notes** * If the `kind` is `src`: * Specify the `src` property. @@ -119,7 +122,7 @@ paths: * Specify the `html` property. * Do not specify the `src` field. * Each app can have 10 scripts installed. - * Multiple scripts can be created [per call](/api-docs/store-management/scripts#notes). + * Multiple scripts can be created [per call](/docs/integrations/scripts#notes). get: summary: Get All Scripts operationId: getScripts @@ -616,15 +619,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -877,7 +880,7 @@ components: script_Response: type: object title: script_Response - description: 'For a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations).' + description: 'For a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations).' properties: data: $ref: '#/components/schemas/script_Full' @@ -887,7 +890,7 @@ components: script_responseCollection: type: object title: script_responseCollection - description: 'For a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations).' + description: 'For a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations).' properties: data: type: array @@ -930,7 +933,7 @@ components: - footer visibility: type: string - description: "Which set of pages the script should load on. \n\nPlease note that you need to have `Checkout content` scope to use `all_pages` and `checkout`.\n\n- The current visibility options are `storefront`, `checkout`, `all_pages` and `order_confirmation`.\n\n `storefront`: All pages that are not `checkout` or `order_confirmation`.\n\n\t\t \nFor a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations)." + description: "Which set of pages the script should load on. \n\nPlease note that you need to have `Checkout content` scope to use `all_pages` and `checkout`.\n\n- The current visibility options are `storefront`, `checkout`, `all_pages` and `order_confirmation`.\n\n `storefront`: All pages that are not `checkout` or `order_confirmation`.\n\n\t\t \nFor a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations)." enum: - storefront - all_pages diff --git a/reference/settings.v3.yml b/reference/settings.v3.yml index f9d534b66..fb2b89139 100644 --- a/reference/settings.v3.yml +++ b/reference/settings.v3.yml @@ -37,6 +37,7 @@ tags: - name: Favicon Image - name: Store Profile - name: Storefront Product + - name: Units of Measurement paths: '/settings/analytics': parameters: @@ -65,6 +66,7 @@ paths: - $ref: '#/components/parameters/Accept' - name: id in: path + description: Web Analytics Provider ID. required: true schema: type: integer @@ -72,12 +74,6 @@ paths: summary: Get a Web Analytics Provider description: Returns a single web analytics provider data for a default channel. parameters: - - name: id - in: path - description: Web Analytics Provider ID. - required: true - schema: - type: integer - $ref: '#/components/parameters/ChannelIdParam' responses: '200': @@ -105,12 +101,6 @@ paths: description: Updates a single web analytics provider data for a default channel. parameters: - $ref: '#/components/parameters/ContentType' - - name: id - in: path - description: Web Analytics Provider ID. - required: true - schema: - type: integer - $ref: '#/components/parameters/ChannelIdParam' requestBody: content: @@ -792,11 +782,12 @@ paths: tags: - Search Filters '/settings/store/locale': - parameters: - - $ref: '#/components/parameters/Accept' get: summary: Get Locale Settings description: Returns global locale settings. + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ChannelIdParam' responses: '200': description: '' @@ -821,9 +812,14 @@ paths: - Store Locale put: summary: Update Locale Settings - description: Updates global locale settings. + description: |- + Updates global locale settings. + + Set a channel override by using the `channel_id` query parameter. To remove a channel override, set `null` for a field. The field then inherits the global value. parameters: + - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' + - $ref: '#/components/parameters/ChannelIdParam' requestBody: content: application/json: @@ -1439,6 +1435,66 @@ paths: tags: - Inventory description: Update inventory settings + /settings/store/units-of-measurement: + get: + summary: Get Units of Measurement Settings + description: |- + Get settings for [units of measurements](https://support.bigcommerce.com/s/article/Store-Settings?language=en_US#physical). + tags: + - Units of Measurement + responses: + '200': + description: 'OK. When you request channel-level settings, `null` indicates that a channel does not have overrides.' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/MeasurementUnitsSettings' + meta: + type: object + '422': + description: The provided settings could not be applied. See detailed errors in the response. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + parameters: + - $ref: '#/components/parameters/ChannelIdParam' + put: + summary: Update Units of Measurement Settings + description: |- + Update settings for [units of measurements](https://support.bigcommerce.com/s/article/Store-Settings?language=en_US#physical). + + The endpoint does not support partial updates. Provide all fields to update global or channel-level settings. + + Create channel-level settings, or overrides for a channel, using the `channel_id` query parameter. + + To delete overrides for a channel, supply `null` as a value for all fields. A channel then inherits global values. + + The endpoint does not support 'null' as a value for global-level settings. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementUnitsSettings' + responses: + '200': + description: 'OK. When you request channel-level settings, `null` indicates that a channel does not have overrides.' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/MeasurementUnitsSettings' + meta: + type: object + parameters: + - $ref: '#/components/parameters/ChannelIdParam' + tags: + - Units of Measurement components: parameters: Accept: @@ -1638,8 +1694,8 @@ components: default: relevance enum: - relevance - - atoz - - ztoa + - alphaasc + - alphadesc title: ContentSortEnumValues x-internal: false DetailedErrors: @@ -1955,19 +2011,19 @@ components: description: |- Describes when stock levels are updated. - Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/api-docs/store-management/webhooks/webhook-events#products), [SKU](/api-docs/store-management/webhooks/webhook-events#skus), and [inventory](/buy-online-pick-up-in-store/webhooks#inventory) webhooks. + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. edit_order_stock_adjustment: type: boolean description: |- Describes whether stock levels automatically adjust when you edit an order. - Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/api-docs/store-management/webhooks/webhook-events#products), [SKU](/api-docs/store-management/webhooks/webhook-events#skus), and [inventory](/buy-online-pick-up-in-store/webhooks#inventory) webhooks. + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. refund_order_stock_adjustment: type: boolean description: |- Describes whether stock levels automatically adjust when you refund or cancel an order. - Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/api-docs/store-management/webhooks/webhook-events#products), [SKU](/api-docs/store-management/webhooks/webhook-events#skus), and [inventory](/buy-online-pick-up-in-store/webhooks#inventory) webhooks. + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. stock_level_display: type: string enum: @@ -2096,11 +2152,12 @@ components: - featured - bestselling - newest - - atoz - - ztoa - - highestprice - - lowestprice - - bestreviewed + - alphaasc + - alphadesc + - pricedesc + - priceasc + - avgcustomerreview + - relevance title: ProductSortEnumValues x-internal: false RobotsTxtSettings: @@ -2250,6 +2307,11 @@ components: type: boolean search_suggest: type: boolean + required: + - content_product_sort + - default_product_sort + - product_filtering_enabled + - search_suggest x-internal: false StorefrontSecuritySettings: type: object @@ -2301,6 +2363,40 @@ components: type: string title: '' x-internal: false + MeasurementUnitsSettings: + type: object + properties: + weight_measurement: + type: string + example: Ounces + enum: + - LBS + - Ounces + - KGS + - Grams + - Tonnes + length_measurement: + type: string + example: Inches + enum: + - Inches + - Centimeters + decimal_token: + type: string + example: '.' + thousands_token: + type: string + example: ',' + decimal_places: + type: integer + example: 2 + factoring_dimension: + type: string + example: depth + enum: + - depth + - height + - width responses: 200-storefront-product-settings: description: OK. `null` indicates that a particular field has not been overridden on a channel level when channel level settings are requested @@ -2329,7 +2425,7 @@ components: properties: '': type: string - example: 'Incorrect value [current__only], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [besling], it should match one of: featured,newest,bestselling,atoz,ztoa,bestreviewed,lowestprice,highestprice' + example: 'Incorrect value [current__only], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [besling], it should match one of: featured, newest, bestselling, alphaasc, alphadesc, avgcustomerreview, priceasc, pricedesc, relevance' minLength: 1 status: type: number @@ -2345,7 +2441,7 @@ components: x-examples: example-1: errors: - '': 'Incorrect value [], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [], it should match one of: featured,newest,bestselling,atoz,ztoa,bestreviewed,lowestprice,highestprice' + '': 'Incorrect value [], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [], it should match one of: featured, newest, bestselling, alphaasc, alphadesc, avgcustomerreview, priceasc, pricedesc, relevance' status: 422 title: JSON data is missing or invalid type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes' @@ -2364,14 +2460,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/shipping.v2.yml b/reference/shipping.v2.yml index 8fc5aff7f..cf585cd16 100644 --- a/reference/shipping.v2.yml +++ b/reference/shipping.v2.yml @@ -1119,7 +1119,6 @@ paths: |:---------|:-----|:------------| | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | Example request body: @@ -1133,7 +1132,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -1333,7 +1331,6 @@ paths: | - | - | - | | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | #### JSON Example @@ -1347,7 +1344,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -1571,7 +1567,6 @@ paths: |:---------|:-----|:------------| | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | Example response: @@ -1585,7 +1580,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -2086,15 +2080,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -2117,7 +2111,6 @@ components: title: Shipping Provider type: string enum: - - '``' - fedex - auspost - canadapost diff --git a/reference/shipping.v3.yml b/reference/shipping.v3.yml index f7dbb125f..3158f23a4 100644 --- a/reference/shipping.v3.yml +++ b/reference/shipping.v3.yml @@ -54,7 +54,7 @@ paths: parameters: - in: query name: 'product_id:in' - description: 'A comma-separated list of product IDs. For more information, see [Filtering](/api-docs/getting-started/filtering).' + description: 'A comma-separated list of product IDs. For more information, see [Filtering](/docs/start/about/common-query-params).' style: form explode: false schema: @@ -273,7 +273,7 @@ components: schema: $ref: '#/components/schemas/error_Full' 429_Too_Many_Requests: - description: 'When an OAuth client exceeds the [rate limit](/api-docs/getting-started/best-practices#api-rate-limits) for API requests to a store.' + description: 'When an OAuth client exceeds the [rate limit](/docs/start/best-practices#api-rate-limits) for API requests to a store.' content: application/json: schema: @@ -305,15 +305,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/shipping_provider.yml b/reference/shipping_provider.yml index c28da00d0..2b2190c06 100644 --- a/reference/shipping_provider.yml +++ b/reference/shipping_provider.yml @@ -3,13 +3,13 @@ info: version: '' title: Shipping Providers description: |- - Implement endpoints consumed by BigCommerce for custom shipping integrations. To learn more, see [Shipping Provider API Overview](/api-docs/store-management/shipping/shipping-provider-api). + Implement endpoints consumed by BigCommerce for custom shipping integrations. To learn more, see [Shipping Provider API Overview](/docs/integrations/shipping). ## Authentication This specification file describes API requests BigCommerce will make to a registered shipping carrierʼs server to check connection options and retrieve rates. As such, the method of authentication is determined by the carrier server. - For more, see [developer-configured authentication](/api-docs/getting-started/authentication#developer-configured-authentication) for provider APIs. + For more, see [developer-configured authentication](/docs/start/authentication#developer-configured-authentication) for provider APIs. ## Subresources @@ -22,10 +22,10 @@ info: ## Additional Information ### Webhooks - - [Shipment](/api-docs/store-management/webhooks/webhook-events#shipment) + - [Shipments](/docs/integrations/webhooks/events#shipments) ### Related API Resources - - [Shipping Provider](/docs/apps-api/shipping) + - [Shipping Provider](/docs/rest-contracts/shipping) - [Shipping V2 API](/docs/rest-management/shipping-v2) termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -853,7 +853,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -869,6 +869,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -972,7 +973,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -988,6 +989,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -1252,7 +1254,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -1268,6 +1270,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -1915,4 +1918,4 @@ components: type: string description: The value of a [shipping address](/docs/rest-management/orders/order-shipping-addresses#get-a-shipping-address) form field. Depending on the form field, this could be a user-defined value or the value of a hidden input. title: Form Field Value - \ No newline at end of file + diff --git a/reference/sites.v3.yml b/reference/sites.v3.yml index 4e2730f30..0037a7f4f 100644 --- a/reference/sites.v3.yml +++ b/reference/sites.v3.yml @@ -7,7 +7,7 @@ info: ## [Sites](/docs/rest-management/sites) - Sites link [headless storefronts](/api-docs/storefronts/developers-guide-headless) to sales [channels](/docs/rest-management/channels). To [create a site](/docs/rest-management/sites#create-a-site), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites`. + Sites link [headless storefronts](/docs/storefront/headless) to sales [channels](/docs/rest-management/channels). To [create a site](/docs/rest-management/sites#create-a-site), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites @@ -43,7 +43,7 @@ info: ## Site routes - [Site routes](/docs/rest-management/sites/site-routes) tell BigCommerce how to link to pages on a [headless storefront](/api-docs/storefronts/developers-guide-headless). To [create a route](/docs/rest-management/sites/site-routes#create-a-site-route) for a [site](#sites), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes`. + [Site routes](/docs/rest-management/sites/site-routes) tell BigCommerce how to link to pages on a [headless storefront](/docs/storefront/headless). To [create a route](/docs/rest-management/sites/site-routes#create-a-site-route) for a [site](#sites), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes @@ -111,8 +111,8 @@ info: ### Related resources * [Channels and Listings Reference](/docs/rest-management/channels) - * [Channels Overview](/api-docs/channels/overview) - * [Building Headless Storefronts Guide](/api-docs/storefronts/developers-guide-headless) + * [Channels Overview](/docs/integrations/channels) + * [Building Headless Storefronts Guide](/docs/storefront/headless) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -166,13 +166,13 @@ paths: $ref: '#/components/responses/504_GatewayTimeout' tags: - Sites - description: 'Create a site that links a [headless storefront](/api-docs/storefronts/developers-guide-headless) to a sales [channel](/docs/rest-management/channels).' + description: 'Create a site that links a [headless storefront](/docs/storefront/headless) to a sales [channel](/docs/rest-management/channels).' get: responses: '200': $ref: '#/components/responses/site_RespCollection' summary: Get Sites - description: 'Get sites linked to a [headless storefront](/api-docs/storefronts/developers-guide-headless) sales channels.' + description: 'Get sites linked to a [headless storefront](/docs/storefront/headless) sales channels.' tags: - Sites parameters: @@ -332,7 +332,7 @@ paths: tags: - Site Routes description: |- - Create routes that tell BigCommerce how to link to pages on a [headless storefront](/api-docs/storefronts/developers-guide-headless). + Create routes that tell BigCommerce how to link to pages on a [headless storefront](/docs/storefront/headless). ## Usage Notes * For a list of supported route types, see [Route types](/docs/rest-management/sites#route-types). @@ -1260,15 +1260,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header parameters: diff --git a/reference/store_content.v2.yml b/reference/store_content.v2.yml index b25af3b56..93be79c3b 100644 --- a/reference/store_content.v2.yml +++ b/reference/store_content.v2.yml @@ -1654,14 +1654,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/store_information.v2.yml b/reference/store_information.v2.yml index d75c6d8a0..985533056 100644 --- a/reference/store_information.v2.yml +++ b/reference/store_information.v2.yml @@ -197,15 +197,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/store_logs.v3.yml b/reference/store_logs.v3.yml index 334f19b1b..5dd8675b4 100644 --- a/reference/store_logs.v3.yml +++ b/reference/store_logs.v3.yml @@ -110,6 +110,16 @@ paths: in: query name: 'id:in' description: 'Query parameter that lets you filter by a list of log IDs, as a CSV. For example ?id:in=3,4,6' + - schema: + type: string + in: query + name: 'date_created:min' + description: 'Query parameter that lets you filter by the minimum date created in [Unix time](https://www.unixtimestamp.com/), for example, `?date_created:min=1657688400`. Returns logs created after this date.' + - schema: + type: string + in: query + name: 'date_created:max' + description: 'Query parameter that lets you filter by the maximum date created in [Unix time](https://www.unixtimestamp.com/), for example, `?date_created:min=1658379600`. Returns logs created before this date.' parameters: [] components: schemas: @@ -210,15 +220,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header tags: diff --git a/reference/storefront_tokens.v3.yml b/reference/storefront_tokens.v3.yml index 4d3f81789..c26f34cbc 100644 --- a/reference/storefront_tokens.v3.yml +++ b/reference/storefront_tokens.v3.yml @@ -2,11 +2,11 @@ openapi: '3.0.1' info: title: Storefront Token description: |- - Get and manage tokens used to authenticate cross-origin requests to the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview). + Get and manage tokens used to authenticate cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql). - ## [API tokens](/docs/storefront-auth/tokens#create-a-token) + ## [API tokens](/docs/rest-authentication/tokens#create-a-token) - Generate tokens (JWT) for authenticating cross-origin requests to the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview). To [create a token](/docs/storefront-auth/tokens#create-a-token), send a `POST` request to `/stores/{{STORE_HASH}}/v3/storefront/api-token`. + Generate tokens (JWT) for authenticating cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql). To [create a token](/docs/rest-authentication/tokens#create-a-token), send a `POST` request to `/stores/{{STORE_HASH}}/v3/storefront/api-token`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token @@ -26,10 +26,10 @@ info: |Property|Type|Description| |-|-|-| |`channel_id`|int| Must be a valid channel ID on the store (required) | - |`expires_at`|int| Unix timestamp (required) | + |`expires_at`|int| Unix timestamp in seconds (required). Does not support milliseconds, microseconds, or nanoseconds. | |`allowed_cors_origins`|array[str]| Allowed origins for cross origin requests (required) | - [**Response:**](/docs/storefront-auth/tokens#create-a-token) + [**Response:**](/docs/rest-authentication/tokens#create-a-token) ```json { @@ -42,9 +42,9 @@ info: - ## [Customer impersonation tokens](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) + ## [Customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) - Generate tokens that can make queries from the perspective of a particular customer in headless or server-side code using the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview#customer-impersonation-tokens). To [create a customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token), send a `POST` request to `/v3/storefront/api-token-customer-impersonation`. + Generate tokens that can make queries from the perspective of a particular customer in headless or server-side code using the [GraphQL Storefront API](/docs/storefront/graphql#customer-impersonation-tokens). To [create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token), send a `POST` request to `/v3/storefront/api-token-customer-impersonation`. ```http POST https://api.bigcommerce.com/stores/{STORE_HASH}/v3/storefront/api-token-customer-impersonation @@ -53,7 +53,7 @@ info: Content-Type: application/json ``` - [**Response:**](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) + [**Response:**](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) ```json { @@ -65,7 +65,7 @@ info: } ``` - Customer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the `X-Bc-Customer-Id` header sent with the GraphQL `POST` request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a [customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) to run a request in the context of customer ID `123`. + Customer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the `X-Bc-Customer-Id` header sent with the GraphQL `POST` request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a [customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) to run a request in the context of customer ID `123`. ```http POST https://store.example.com/graphql @@ -85,7 +85,7 @@ info: ## Revoking tokens - To [revoke a token](/docs/storefront-auth/tokens#revoke-a-token), send a `DELETE` request to `/v3/storefront/api-token`. + To [revoke a token](/docs/rest-authentication/tokens#revoke-a-token), send a `DELETE` request to `/v3/storefront/api-token`. ```http DELETE /stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation @@ -96,7 +96,7 @@ info: ## Additional information - * [GraphQL API Overview](/api-docs/storefront/graphql/graphql-storefront-api-overview) + * [GraphQL API Overview](/docs/storefront/graphql) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -190,7 +190,7 @@ paths: - Customer Impersonation Token summary: Create a Token description: |- - Returns a Storefront API token that allows your application to impersonate customers when making GraphQL `POST` requests. For more information on how to use the returned token, see [customer impersonation tokens](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token). + Returns a Storefront API token that allows your application to impersonate customers when making GraphQL `POST` requests. For more information on how to use the returned token, see [customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token). **Required Scopes** * `Manage` `Storefront API Customer Impersonation Tokens` @@ -250,7 +250,7 @@ components: example: 1 expires_at: type: integer - description: Unix timestamp (UTC time) defining when the token should expire. + description: Unix timestamp (UTC time) defining when the token should expire. Supports seconds, but does not support milliseconds, microseconds, or nanoseconds. example: 1885635176 minimum: 0 required: @@ -342,15 +342,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). name: X-Auth-Token in: header diff --git a/reference/subscribers.v3.yml b/reference/subscribers.v3.yml index f0611f1d2..715f53778 100644 --- a/reference/subscribers.v3.yml +++ b/reference/subscribers.v3.yml @@ -905,15 +905,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/subscriptions.sf.yml b/reference/subscriptions.sf.yml index d5c1b3202..e5eb799e0 100644 --- a/reference/subscriptions.sf.yml +++ b/reference/subscriptions.sf.yml @@ -4,15 +4,15 @@ info: description: |- Manage newsletter and marketing email subscriptions on the storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). ## Additional Information * [Collecting Newsletter Subscriptions](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions) (support.bigcommerce.com) - * [Customers Overview](/api-docs/customers/customers-subscribers-overview) - * [Working with Storefront APIs](/api-docs/cart-and-checkout/working-sf-apis) + * [Customers Overview](/docs/store-operations/customers/customers-subscribers-overview) + * [Working with Storefront APIs](/docs/storefront/cart-checkout/guide/rest-storefront) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce diff --git a/reference/tax.v3.yml b/reference/tax.v3.yml index bd2c0e9e9..58e9ee964 100644 --- a/reference/tax.v3.yml +++ b/reference/tax.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.0' info: title: Tax Provider Connection version: '3' - description: 'Manage the connection between a merchantʼs BigCommerce store and a third party tax provider. For more information, see [Tax Provider API Overview](/api-docs/providers/tax).' + description: 'Manage the connection between a merchantʼs BigCommerce store and a third party tax provider. For more information, see [Tax Provider API Overview](/docs/integrations/tax).' termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -49,11 +49,11 @@ paths: delete: summary: Delete a Connection description: | - Remove any previously set basic connection credentials for the specified provider. If the specified provider is the active tax provider on the store, the store's active tax provider will be reset to BigCommerce Manual Tax. It is suggested to call this endpoint during a single-click app [uninstall callback](/api-docs/apps/guide/callbacks#uninstall-callback). + Remove any previously set basic connection credentials for the specified provider. If the specified provider is the active tax provider on the store, the store's active tax provider will be reset to BigCommerce Manual Tax. It is suggested to call this endpoint during a single-click app [uninstall callback](/docs/integrations/apps/guide/callbacks#uninstall-callback). > #### Note > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs) under **Staff Actions**. - > * Requires **write** permissions on the **Information and Settings** [scope](/api-docs/getting-started/api-accounts#oauth-scopes). + > * Requires **write** permissions on the **Information and Settings** [scope](/docs/start/authentication/api-accounts#oauth-scopes). operationId: provider-connection-delete responses: '200': @@ -96,11 +96,11 @@ paths: - (optional) Tax provider profile used in customized endpoint urls for tax provider calls. This is only available for tax providers that support this feature. The configured `username`, `password`, and `profile` (if available) is used to authenticate each API request to the Tax Provider from the associated store. - The tax provider's `profile` will be included in the url for [Tax Provider API](/docs/apps-api/tax) endpoints. + The tax provider's `profile` will be included in the url for [Tax Provider API](/docs/rest-contracts/tax) endpoints. > #### Note > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs) under **Staff Actions**. - > * Requires **write** permissions on the **Information and Settings** [scope](/api-docs/getting-started/api-accounts#oauth-scopes). + > * Requires **write** permissions on the **Information and Settings** [scope](/docs/start/authentication/api-accounts#oauth-scopes). summary: Update a Connection parameters: - $ref: '#/components/parameters/ContentType' @@ -138,7 +138,7 @@ paths: required: true schema: type: string - description: 'The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider details](/api-docs/providers/tax#sharing-provider-details-with-bigcommerce).' + description: 'The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider details](/docs/integrations/tax#sharing-provider-details-with-bigcommerce).' components: parameters: Accept: @@ -179,15 +179,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/tax_classes.v2.yml b/reference/tax_classes.v2.yml index cc42d906e..cb821f28e 100644 --- a/reference/tax_classes.v2.yml +++ b/reference/tax_classes.v2.yml @@ -174,15 +174,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/tax_properties.v3.yml b/reference/tax_properties.v3.yml index a2bff3fd8..e0c292f0c 100644 --- a/reference/tax_properties.v3.yml +++ b/reference/tax_properties.v3.yml @@ -269,15 +269,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/tax_provider.yml b/reference/tax_provider.yml index c56b07893..5856f225e 100644 --- a/reference/tax_provider.yml +++ b/reference/tax_provider.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Tax Provider API version: '1.0' - description: 'Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports [estimate](/docs/apps-api/tax#estimate-taxes), [adjust](/docs/apps-api/tax#adjust-tax-quote), [commit](/docs/apps-api/tax#commit-tax-quote), and [void](/docs/apps-api/tax#void-tax-quote) operations. For more information, see [Tax Provider API Overview](/api-docs/providers/tax).' + description: 'Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports [estimate](/docs/rest-contracts/tax#estimate-taxes), [adjust](/docs/rest-contracts/tax#adjust-tax-quote), [commit](/docs/rest-contracts/tax#commit-tax-quote), and [void](/docs/rest-contracts/tax#void-tax-quote) operations. For more information, see [Tax Provider API Overview](/docs/integrations/tax).' termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -1317,9 +1317,9 @@ components: type: http scheme: basic description: |- - The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials used to authenticate each API request to the Tax Provider from the associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a Connection](/docs/apps-api/tax-app-connection#update-a-connection) request. `profile` is an optional field and will be used with supporting providers only. + The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials used to authenticate each API request to the Tax Provider from the associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) request. `profile` is an optional field and will be used with supporting providers only. - For more, see [developer-configured authentication](/api-docs/getting-started/authentication#developer-configured-authentication) for Provider APIs. + For more, see [developer-configured authentication](/docs/start/authentication#developer-configured-authentication) for Provider APIs. security: - Authorization: [] diff --git a/reference/tax_rates_zones.v3.yml b/reference/tax_rates_zones.v3.yml index dbd18f6c0..ffbb892a5 100644 --- a/reference/tax_rates_zones.v3.yml +++ b/reference/tax_rates_zones.v3.yml @@ -416,15 +416,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). schemas: Tax_Zone: type: object diff --git a/reference/tax_settings.v3.yml b/reference/tax_settings.v3.yml index a5c30a07d..bf2e88bf0 100644 --- a/reference/tax_settings.v3.yml +++ b/reference/tax_settings.v3.yml @@ -51,7 +51,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Tax_Settings_Req' + $ref: '#/components/schemas/Tax_Settings' required: true responses: '200': @@ -102,15 +102,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -143,41 +143,22 @@ components: - FIXED - BASIC - DISABLE - should_subtract_store_tax: - default: true - type: boolean - description: This setting applies only if a merchant enters tax-inclusive prices. When enabled, the store subtracts the itemʼs store tax rate before calculating tax using the shopperʼs tax zone. The tax-exclusive amount will be the same across all tax zones. When disabled, the tax-inclusive price remains the same across all tax zones; only the tax amount will vary based on the shopperʼs location. The tax-exclusive amount may vary among tax zones. These calculations are relevant for tax pricing and tax quotations that use basic tax. - Tax_Settings_Req: - type: object - properties: - tax_entered_with_prices: - type: boolean - description: Whether prices entered on this store include a tax component or not. - price_display_settings: - type: object - description: Settings that describe how prices display at the global level. - properties: - show_inclusive_in_control_panel: - type: boolean - description: Whether to show prices as tax inclusive or tax exclusive in the BigCommerce control panel. - invoice_price_display_strategy: - type: string - description: 'Whether to show prices as tax inclusive or tax exclusive across all invoices, or use the shopperʼs tax zone for price display on invoices.' - enum: - - ZONE - - INCLUSIVE - - EXCLUSIVE - fallback_strategy: - type: string - description: 'Decribes the fallback behaviour that applies when a tax provider produces an error. A merchant may decide to use a flat 10% fallback tax rate, their basic tax settings, or to block the transaction until a successful result can be achieved.' - enum: - - FIXED - - BASIC - - DISABLE should_subtract_store_tax: default: true type: boolean description: This setting applies only if a merchant enters tax-inclusive prices. When enabled, the store subtracts the itemʼs store tax rate before calculating tax using the shopperʼs tax zone. The tax-exclusive amount will be the same across all tax zones. When disabled, the tax-inclusive price remains the same across all tax zones; only the tax amount will vary based on the shopperʼs location. The tax-exclusive amount may vary among tax zones. These calculations are relevant for tax pricing and tax quotations that use basic tax. + should_use_geolocation_to_determine_guest_shopper_tax_zone: + default: false + type: boolean + description: This setting determines which tax zone a store uses to estimate tax for guest shoppers. When enabled, the store identifies a country-level tax zone based on the geolocation of a guest shopper. The store then applies the corresponding tax zone to estimate taxes. When disabled, the store identifies the zone using the provided `guest_shopper_tax_zone_id` field instead. Only the tax zones you configure can be matched to the guest shopper's geolocation. + guest_shopper_tax_zone_id: + default: 1 + type: integer + description: ID for the tax zone a store uses when estimating tax for guest shoppers. The store uses this zone if you disable `should_use_geolocation_to_determine_guest_shopper_tax_zone`. The store also uses this zone if there is no matching country-level tax zone for the geolocation. + store_tax_zone_id: + default: 1 + type: integer + description: ID for the tax zone a store uses when subtracting store tax. This setting applies only if a merchant enters tax-inclusive prices and subtracts store tax before tax calculation. MetaOpen: title: Response meta type: object diff --git a/reference/themes.v3.yml b/reference/themes.v3.yml index 4f976d0ce..fdb47f8c9 100644 --- a/reference/themes.v3.yml +++ b/reference/themes.v3.yml @@ -465,7 +465,7 @@ paths: additionalProperties: true title: Detailed Errors title: Error Response - description: 'Returns a theme *Job*. If job is completed, the result is included in the response.' + description: 'Returns a theme *Job*. When the job is complete, the results array provides a generated link to access the theme. The link is active for 60 seconds.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/JobIdParam' @@ -507,11 +507,6 @@ paths: description: Filter configurations by a variation_uuid. parameters: - $ref: '#/components/parameters/Accept' - - schema: - type: string - name: uuid - in: path - required: true - in: query name: 'site_id:in' description: Filter configurations by a list of site_ids @@ -699,7 +694,7 @@ components: items: $ref: '#/components/schemas/themeConfiguration_Full' meta: - $ref: '#/components/schemas/CollectionMeta' + $ref: '#/components/schemas/ThemesCollectionMeta' examples: response: value: @@ -717,10 +712,6 @@ components: per_page: 50 current_page: 1 total_pages: 1 - links: - previous: nostrud in - current: '?page=1&limit=50' - next: in securitySchemes: X-Auth-Token: name: X-Auth-Token @@ -735,15 +726,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -801,6 +792,42 @@ components: Link to the next page returned in the response. title: Collection Meta x-internal: false + ThemesCollectionMeta: + type: object + description: 'Data about the response, including pagination and collection totals.' + properties: + pagination: + type: object + description: 'Data about the response, including pagination and collection totals.' + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + title: Themes Collection Meta + x-internal: false Pagination: type: object description: 'Data about the response, including pagination and collection totals.' diff --git a/reference/webhooks.v3.yml b/reference/webhooks.v3.yml index e5a7d3eef..7b3465e18 100644 --- a/reference/webhooks.v3.yml +++ b/reference/webhooks.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Webhooks v3 version: '' - description: 'Get notified when specific events occur on a BigCommerce store. For more information, see [Webhooks Overview](/api-docs/store-management/webhooks/overview).' + description: 'Get notified when specific events occur on a BigCommerce store. For more information, see [Webhooks Overview](/docs/integrations/webhooks).' termsOfService: 'https://www.bigcommerce.com/terms' contact: email: support@bigcommerce.com @@ -227,7 +227,7 @@ paths: description: You can pass in any number of custom headers to validate webhooks being returned. is_active: type: boolean - description: If webhook is active or not + description: If the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity. default: true created_at: type: integer @@ -235,6 +235,13 @@ paths: updated_at: type: integer description: Updated time + status: + type: string + description: The webhook status. + enum: + - inactive + - active + - deactivated blocked_domains: description: List of domains (destinations) that are currently on the denylist and are not being sent webhooks. type: array @@ -358,7 +365,7 @@ components: name: is_active in: query description: | - Enables user to filter for webhooks that are active or not. + Enables user to filter for webhooks that are active or not. A webhook subscription becomes deactivated after 90 days of inactivity. schema: type: boolean example: true @@ -653,15 +660,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -685,11 +692,11 @@ components: This webhook fires on new cart creation when any of the following occur: * a storefront shopper adds their first product to a cart during a new session * an application makes a successful `POST` request to `/carts` using either the [REST Storefront](/docs/rest-storefront/carts#create-a-cart) API or the [REST Management](/docs/rest-management/carts/carts-single#create-a-cart) API - * a storefront makes a successful call to create a cart using the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout) + * a storefront makes a successful call to create a cart using the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront) Cart creation also fires the `store/cart/updated` webhook. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -732,8 +739,8 @@ components: title: store/cart/updated description: |- Fires when one of the following occurs: - * A cartʼs line items are modified by adding a new item to a cart, updating an existing itemʼs quantity, or deleting an item. - * A shopper enters or changes their email address during guest checkout. This includes signing in to a customer account after creating a guest cart, which associates the accountʼs email address with the cart. + * A cart's line items are modified by adding a new item to a cart, updating an existing item's quantity, or deleting an item. + * A shopper enters or changes their email address during guest checkout. This includes signing in to a customer account after creating a guest cart, which associates the account's email address with the cart. The `store/cart/created` webhook firing also triggers this webhook because adding a product to an empty cart is considered an update. @@ -741,7 +748,7 @@ components: * Quantity * Item Price - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -782,7 +789,7 @@ components: Fires when a cart is deleted. Carts are deleted in two ways; when all items are removed from a cart, and when an API consumer explicitly removes the cart using a `DELETE` request. Cart deletion ends the cart lifecycle. The `store/cart/updated` webhook also fires when the last item is removed. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -822,7 +829,7 @@ components: description: |- Fires when a new coupon code is applied to a cart. The webhook request body includes the ID of the coupon code. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -868,7 +875,7 @@ components: This webhook fires after a cart is abandoned. BigCommerce considers a cart abandoned when it has no activity for at least one hour. This webhook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -912,7 +919,7 @@ components: Fires when a cart/checkout is converted into an order, which is typically after the checkout payment step on the storefront. At this point, the cart is automatically deleted and no longer accessible. This webhook returns both the cart/checkout ID and order ID for correlation purposes. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -957,7 +964,7 @@ components: description: |- This webhook subscribes to all cart line item events. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -998,7 +1005,7 @@ components: description: |- Fires when a new item is added to the cart. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1047,7 +1054,7 @@ components: * Quantity * Item Price - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1092,7 +1099,7 @@ components: description: |- Fires when an item is deleted from the cart. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1147,7 +1154,7 @@ components: description: |- Fires when a category is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1191,7 +1198,7 @@ components: * Enable Google Shopping - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1230,7 +1237,7 @@ components: description: |- Fires when a category is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1277,7 +1284,7 @@ components: description: |- Fires when a channel is created in the control panel or by API. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1328,7 +1335,7 @@ components: * config_meta - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1379,7 +1386,7 @@ components: description: |- Fires when a new customer is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1419,10 +1426,10 @@ components: store_customer_updated: title: store/customer/updated description: |- - This webhook is triggered when a customer is updated. In addition, this webhook is triggered when a shopper initially enters custom form field values within the account sign-up form. Please note that neither changing existing data in customer form fields nor changing a customerʼs address will trigger the webhook. + This webhook is triggered when a customer is updated. In addition, this webhook is triggered when a shopper initially enters custom form field values within the account sign-up form. Please note that neither changing existing data in customer form fields nor changing a customer's address will trigger the webhook. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1464,7 +1471,7 @@ components: description: |- This webhook is triggered when a customer is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1505,7 +1512,7 @@ components: description: |- Fires when a customer address is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1555,7 +1562,7 @@ components: description: |- Fires when a customer address is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1605,7 +1612,7 @@ components: description: |- Fires when a customer address is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1655,7 +1662,7 @@ components: description: |- Fires when a customer default payment instrument is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1701,7 +1708,7 @@ components: description: |- This webhook is triggered when an order is created in the control panel, using an app, or by API. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1762,7 +1769,7 @@ components: * Release Date * Remove pre-order status on this date - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1803,7 +1810,7 @@ components: description: |- Fires when an order is archived. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1843,7 +1850,7 @@ components: description: |- This webhook is triggered when an order status changes; for example, from `Pending` to `Awaiting Payment`. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1898,7 +1905,7 @@ components: description: |- This webhook is triggered when an order message is created by a customer or in the control panel. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1948,7 +1955,7 @@ components: description: |- This webhook is triggered when a refund is submitted against an order. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2003,7 +2010,7 @@ components: description: |- This webhook is triggered when a product is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2044,7 +2051,7 @@ components: description: |- Fires when a new product is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2137,7 +2144,7 @@ components: * Product Files * Customs Information - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2186,7 +2193,7 @@ components: * Inventory Low Stock - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2254,7 +2261,7 @@ components: Changes to the following fields trigger this event: * Quantity - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2324,7 +2331,7 @@ components: description: |- Fires when a shipment is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2372,7 +2379,7 @@ components: Changes to the following fields trigger this event: * Shipping Tracking Number - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2417,7 +2424,7 @@ components: description: |- This webhook is triggered when a shipment is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2467,7 +2474,7 @@ components: description: |- This webhook is triggered when a new SKU is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2522,7 +2529,7 @@ components: description: |- Fires when a SKU is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2577,7 +2584,7 @@ components: description: |- Fires when a SKU is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2632,7 +2639,7 @@ components: description: |- Fires when a SKU is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2705,7 +2712,7 @@ components: Changes to the following fields trigger this event: * Quantity - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2775,7 +2782,7 @@ components: description: |- Fires when a client store is canceled and uninstalled from the platform. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2818,7 +2825,7 @@ components: * Email * Phone - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2858,7 +2865,7 @@ components: description: |- Fires when a subscriber is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2898,7 +2905,7 @@ components: description: |- The webhook fires when a subscriber is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2938,7 +2945,7 @@ components: description: |- This webhook is triggered when a subscriber is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -3023,7 +3030,7 @@ components: is_active: type: boolean example: true - description: Boolean value that indicates whether the webhook is active or not. + description: Boolean value that indicates whether the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity. events_history_enabled: type: boolean example: true diff --git a/reference/widgets.v3.yml b/reference/widgets.v3.yml index 5e2ea9db2..3dc19e234 100644 --- a/reference/widgets.v3.yml +++ b/reference/widgets.v3.yml @@ -8,7 +8,7 @@ info: ## Subresources ### Widget templates - [Widget templates](/rest-content/widgets/widget-template) are reusable Handlebars-enabled HTML templates that define the structure of the widget on a page. + [Widget templates](/docs/rest-content/widgets/widget-template) are reusable Handlebars-enabled HTML templates that define the structure of the widget on a page. ### Widgets [Widgets](/docs/rest-content/widgets/widget) are units of content placed on specific pages in a Stencil theme. Widgets consist of a widget configuration and a widget template UUID and render as part of the storefront’s HTML. @@ -21,9 +21,9 @@ info: ## Additional Information - * [Widgets API Overview](/api-docs/store-management/widgets/overview) - * [Widget UI Schema](/stencil-docs/page-builder/widget-ui-schema) - * [Widget UI Input Types](/stencil-docs/page-builder/schema-settings) + * [Widgets API Overview](/docs/storefront/widgets) + * [Widget UI Schema](/docs/storefront/widgets/input-reference/schema) + * [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -443,7 +443,7 @@ paths: **Template Files** - To view the list of values accepted by the `template_file` property, including **custom** templates, see [Placements](/api-docs/store-management/widgets/overview#placements). + To view the list of values accepted by the `template_file` property, including **custom** templates, see [Placements](/docs/storefront/widgets#placements). get: tags: - Placement @@ -753,11 +753,11 @@ components: description: The HTML layout which defines complex positioning for placements. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. title: Layout meta: @@ -854,11 +854,11 @@ components: description: The HTML layout which defines complex positioning for placements. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. title: Layout PlacementsCollection_Resp: @@ -1294,15 +1294,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -1385,11 +1385,11 @@ components: description: The kind of widget template. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. current_version_uuid: type: string @@ -1415,11 +1415,11 @@ components: $ref: '#/components/schemas/widgetTemplate_Full' date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. version_uuid: type: string @@ -1517,11 +1517,11 @@ components: description: The template file that you would like to target. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. channel_id: type: integer @@ -1750,18 +1750,18 @@ components: example: Product settings: type: array - description: 'For examples of schema settings, see [Widget UI Input Types](/stencil-docs/page-builder/schema-settings).' + description: 'For examples of schema settings, see [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings).' items: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean @@ -1835,7 +1835,7 @@ components: type: string settings: type: array - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' items: $ref: '#/components/schemas/widgetSchemaSetting_Base' x-internal: false @@ -1879,14 +1879,14 @@ components: widgetSchemaSetting_Base: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean @@ -1932,7 +1932,7 @@ components: x-internal: false widgetSchema: type: array - description: 'The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/stencil-docs/page-builder/widget-ui-schema). ' + description: 'The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/docs/storefront/widgets/input-reference/schema). ' title: '' items: anyOf: @@ -1956,14 +1956,14 @@ components: items: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean diff --git a/reference/wishlists.v3.yml b/reference/wishlists.v3.yml index 3faa8c029..13988d961 100644 --- a/reference/wishlists.v3.yml +++ b/reference/wishlists.v3.yml @@ -2,10 +2,11 @@ openapi: '3.0.1' info: title: Wishlist description: |- - Create and manage customer [wishlists](https://support.bigcommerce.com/s/article/Wishlists). + Create and manage customer wishlists and wishlist items. ## Additional Information - * [Wishlists](https://support.bigcommerce.com/s/article/Wishlists) + + * [Wishlists (Help Center)](https://support.bigcommerce.com/s/article/Wishlists) version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -23,7 +24,6 @@ security: - X-Auth-Token: [] tags: - name: Wishlists - description: '' - name: Wishlists Items paths: '/wishlists': @@ -241,23 +241,22 @@ paths: type: string type: type: string - x-codegen-request-body-name: body '/wishlists/{wishlist_id}/items/{item_id}': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' + - name: item_id + in: path + required: true + schema: + type: integer + format: int32 delete: tags: - Wishlists Items summary: Delete Wishlist Item description: Deletes a wishlist item. operationId: WishlistsItemsByIdDelete - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - - name: item_id - in: path - required: true - schema: - type: integer - format: int32 responses: '200': description: '' @@ -334,15 +333,15 @@ paths: type: type: string '/wishlists/{wishlist_id}': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' get: tags: - Wishlists summary: Get a Wishlist description: Returns a single wishlist. operationId: WishlistsByIdGet - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' responses: '200': description: '' @@ -425,11 +424,9 @@ paths: description: |- Updates a wishlist. - Use this endpoint to update existing wishlist items, change the wishlist's name and whether the wishlist is available publicly. To add or delete a wishlist item, see [Wishlist Items](/docs/rest-management/wishlists/wishlists-items). + Use this endpoint to update existing wishlist items, change the wishlistʼs name and whether the wishlist is available publicly. To add or delete a wishlist item, see [Wishlist Items](/docs/rest-management/wishlists/wishlists-items). operationId: WishlistsByIdPut parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -506,16 +503,12 @@ paths: type: string type: type: string - x-codegen-request-body-name: body delete: tags: - Wishlists summary: Delete a Wishlist description: Deletes a wishlist. operationId: WishlistsByIdDelete - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' responses: '204': description: '' @@ -551,6 +544,9 @@ paths: type: type: string '/wishlists/{wishlist_id}/items': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' post: tags: - Wishlists Items @@ -558,8 +554,6 @@ paths: description: Adds a wishlist item. More than one item can be added at a time. operationId: WishlistsItemsByIdPost parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -627,7 +621,6 @@ paths: '500': description: Internal server error. content: {} - x-codegen-request-body-name: body components: schemas: wishlist_Post: @@ -806,18 +799,6 @@ components: format: int32 description: 'Data about the response, including pagination and collection totals.' x-internal: false - error: - title: error - type: object - properties: - status: - type: integer - format: int32 - title: - type: string - type: - type: string - x-internal: false metaCollection: title: metaCollection type: object @@ -825,150 +806,7 @@ components: pagination: $ref: '#/components/schemas/pagination' x-internal: false - responses: - Unauthorized: - description: Authentication information is missing or invalid. - content: - application/json: - schema: - title: Error - type: object - properties: - status: - type: integer - format: int32 - title: - type: string - type: - type: string - Wishlist_Resp: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/wishlist_Full' - meta: - type: object - properties: {} - additionalProperties: true - description: Response metadata. - example: - data: - id: 30 - customer_id: 10 - name: Christmas List - is_public: true - token: d2d55481-13eb-4d1e-9d79-9062b518570d - items: - - id: 44 - product_id: 77 - variant_id: 1 - - id: 45 - product_id: 80 - variant_id: 1 - - id: 46 - product_id: 81 - variant_id: 1 - - id: 47 - product_id: 86 - variant_id: 1 - - id: 48 - product_id: 88 - variant_id: 1 - meta: {} - wishlist_Resp_Collection: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/wishlist_Full' - meta: - $ref: '#/components/schemas/metaCollection' - example: - data: - - id: 1 - customer_id: 4 - name: My Wish List - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570d - items: [] - - id: 2 - customer_id: 11 - name: Christmas - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570e - items: - - id: 1 - product_id: 167 - - id: 2 - product_id: 174 - - id: 3 - product_id: 184 - - id: 3 - customer_id: 20 - name: Birthday - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 4 - product_id: 184 - - id: 5 - product_id: 183 - - id: 4 - customer_id: 20 - name: Christmas - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 6 - product_id: 201 - - id: 5 - customer_id: 19 - name: Wish List - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 7 - product_id: 173 - - id: 8 - product_id: 176 - meta: - pagination: - total: 0 - count: 5 - per_page: 50 - current_page: 1 - total_pages: 0 parameters: - FilterCustomerID: - name: customer_id - in: query - description: All wishlists relating to the customer. - schema: - type: integer - format: int32 - FilterPage: - name: page - in: query - description: The page number of results per page. 1 is the default and starts from record 0. - schema: - type: integer - format: int32 - FilterLimit: - name: limit - in: query - description: The numbers of items to return per page. Default is 50 and maximum is 250. - schema: - type: integer - format: int32 WishlistID: name: wishlist_id in: path @@ -1008,15 +846,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header