bigcommerce-ruby 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d1dd058efb06fed8a75053e596034ec4d376c166abbe87bddda3692bdac1d14
+  data.tar.gz: 5edcdfa976ffd5abc8da00accab5ca75f4686796ea213a8253f9301fd802460d
+SHA512:
+  metadata.gz: 96b0e6f1ba1fc463faf40200f2cc9c9270f22023c9a3600e6a1aed2bb91d6bc4845dc530e7121bcf03bc885359fef02280340641a5aef96b25a6854d1db23a3e
+  data.tar.gz: f4323fa4d78e907940e14c651ab56a5ea9083e27e7e7e9491337aefe16dd0269d4d32b57ef3ca8111059318f55eede65d217a6538f50be120dba5edf9eb73f7f

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0 (2026-02-24)
+
+- Abandoned cart settings resource
+- Abandoned carts resource
+- Inventory adjustments resource
+- Inventory items resource
+
+## 0.1.0 (2026-02-17)
+
+- Initial release
+- Orders V2 API support: CRUD, count, archive
+- Order sub-resources: products, shipments, shipping addresses, coupons, taxes, messages, fees, statuses
+- Automatic retry with exponential backoff for rate limits and server errors
+- Typed error classes for all HTTP error codes

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alvaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,215 @@
+# bigcommerce-ruby
+
+A Ruby gem for the BigCommerce REST Management API. Thin, idiomatic, and built on Faraday — no magic, just clean API access with automatic retries and proper error handling.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "bigcommerce-ruby"
+```
+
+```
+gem install bigcommerce-ruby
+```
+
+## Configuration
+
+**Global** (recommended for Rails apps):
+
+```ruby
+Bigcommerce.configure do |config|
+  config.store_hash   = ENV["BIGCOMMERCE_STORE_HASH"]
+  config.access_token = ENV["BIGCOMMERCE_ACCESS_TOKEN"]
+  config.timeout      = 30  # optional, default: 30s
+  config.open_timeout = 10  # optional, default: 10s
+end
+
+client = Bigcommerce.client
+```
+
+**Per-client** (useful for multi-tenant apps):
+
+```ruby
+client = Bigcommerce::Client.new(
+  store_hash: "your_store_hash",
+  access_token: "your_access_token"
+)
+```
+
+## Usage
+
+### Orders
+
+```ruby
+# List with filtering, sorting, and pagination
+client.orders.list(page: 1, limit: 25)
+client.orders.list(status_id: 11, min_date_created: "2025-01-01")
+client.orders.list(sort: "date_created", direction: "desc", customer_id: 42)
+
+# Single order
+client.orders.find(100)
+
+# Create
+client.orders.create(
+  customer_id: 1,
+  billing_address: {
+    first_name: "John",
+    last_name: "Doe",
+    street_1: "123 Main St",
+    city: "Austin",
+    state: "TX",
+    zip: "78701",
+    country: "United States",
+    country_iso2: "US",
+    email: "john@example.com"
+  },
+  products: [
+    { product_id: 10, quantity: 2 }
+  ]
+)
+
+# Update
+client.orders.update(100, status_id: 2, staff_notes: "Shipped today")
+
+# Archive
+client.orders.archive(100)
+
+# Count
+client.orders.count
+client.orders.count(status_id: 11)
+```
+
+### Order Products
+
+```ruby
+products = client.order_products(100)
+
+products.list
+products.list(page: 1, limit: 10)
+products.find(5)
+```
+
+### Order Shipments
+
+```ruby
+shipments = client.order_shipments(100)
+
+shipments.list
+shipments.find(1)
+shipments.count
+
+shipments.create(
+  order_address_id: 1,
+  items: [{ order_product_id: 10, quantity: 1 }],
+  tracking_number: "ABC123",
+  shipping_provider: "usps"
+)
+
+shipments.update(1, tracking_number: "XYZ789")
+shipments.destroy(1)
+shipments.destroy_all
+```
+
+### Order Shipping Addresses
+
+```ruby
+addresses = client.order_shipping_addresses(100)
+
+addresses.list
+addresses.find(1)
+addresses.update(1, city: "Dallas", state: "TX")
+```
+
+### Order Coupons
+
+```ruby
+client.order_coupons(100).list
+```
+
+### Order Taxes
+
+```ruby
+client.order_taxes(100).list
+client.order_taxes(100).list(details: "true")
+```
+
+### Order Messages
+
+```ruby
+messages = client.order_messages(100)
+messages.list
+messages.list(status: "unread", is_flagged: true)
+```
+
+### Order Fees
+
+```ruby
+client.order_fees(100).list
+```
+
+### Order Statuses
+
+```ruby
+client.order_statuses.list
+client.order_statuses.find(1)
+```
+
+## Response
+
+Every method returns a `Bigcommerce::Response`:
+
+```ruby
+response = client.orders.list
+
+response.body             # Parsed JSON — Hash or Array with symbol keys
+response.status           # HTTP status code
+response.headers          # Response headers
+response.success?         # true for 2xx
+response.rate_limit       # Remaining API calls
+response.rate_limit_reset # Time until reset (ms)
+```
+
+## Error Handling
+
+Errors map directly to HTTP status codes:
+
+```ruby
+begin
+  client.orders.find(999)
+rescue Bigcommerce::NotFoundError
+  puts "Order not found"
+rescue Bigcommerce::AuthenticationError
+  puts "Bad credentials — check your access token"
+rescue Bigcommerce::RateLimitError => e
+  puts "Rate limited, retry after #{e.response.rate_limit_reset}ms"
+rescue Bigcommerce::UnprocessableEntityError => e
+  puts "Validation error: #{e.message}"
+rescue Bigcommerce::ServerError
+  puts "BigCommerce server error"
+rescue Bigcommerce::ApiError => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+| Error class | HTTP status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `NotFoundError` | 404 |
+| `UnprocessableEntityError` | 422 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `ApiError` | anything else |
+
+Requests that hit 429 or 5xx are automatically retried up to 3 times with exponential backoff. On a 429, the gem reads the `x-rate-limit-time-reset-ms` header and sleeps accordingly before retrying.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/bigcommerce/client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  class Client
+    attr_reader :config, :connection
+
+    def initialize(store_hash: nil, access_token: nil, **options)
+      @config = Configuration.new
+      @config.store_hash = store_hash || Bigcommerce.configuration.store_hash
+      @config.access_token = access_token || Bigcommerce.configuration.access_token
+      @config.timeout = options[:timeout] if options[:timeout]
+      @config.open_timeout = options[:open_timeout] if options[:open_timeout]
+      @config.validate!
+      @connection = Connection.new(@config)
+    end
+
+    def orders
+      @orders ||= Resources::Orders.new(connection)
+    end
+
+    def order_products(order_id)
+      Resources::OrderProducts.new(connection, order_id)
+    end
+
+    def order_shipments(order_id)
+      Resources::OrderShipments.new(connection, order_id)
+    end
+
+    def order_shipping_addresses(order_id)
+      Resources::OrderShippingAddresses.new(connection, order_id)
+    end
+
+    def order_coupons(order_id)
+      Resources::OrderCoupons.new(connection, order_id)
+    end
+
+    def order_taxes(order_id)
+      Resources::OrderTaxes.new(connection, order_id)
+    end
+
+    def order_messages(order_id)
+      Resources::OrderMessages.new(connection, order_id)
+    end
+
+    def order_fees(order_id)
+      Resources::OrderFees.new(connection, order_id)
+    end
+
+    def order_statuses
+      @order_statuses ||= Resources::OrderStatuses.new(connection)
+    end
+
+    def abandoned_carts
+      @abandoned_carts ||= Resources::AbandonedCarts.new(connection)
+    end
+
+    def abandoned_cart_settings
+      @abandoned_cart_settings ||= Resources::AbandonedCartSettings.new(connection)
+    end
+
+    def inventory_items
+      @inventory_items ||= Resources::InventoryItems.new(connection)
+    end
+
+    def inventory_adjustments
+      @inventory_adjustments ||= Resources::InventoryAdjustments.new(connection)
+    end
+  end
+end

data/lib/bigcommerce/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  class Configuration
+    attr_accessor :store_hash, :access_token, :timeout, :open_timeout
+
+    def initialize
+      @store_hash = nil
+      @access_token = nil
+      @timeout = 30
+      @open_timeout = 10
+    end
+
+    def validate!
+      raise ConfigurationError, "store_hash is required" if store_hash.nil? || store_hash.empty?
+      raise ConfigurationError, "access_token is required" if access_token.nil? || access_token.empty?
+    end
+  end
+end

data/lib/bigcommerce/connection.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module Bigcommerce
+  class Connection
+    BASE_URL = "https://api.bigcommerce.com/stores"
+
+    def initialize(config)
+      @config = config
+    end
+
+    def get(path, params = {}, api_version: :v2)
+      request(:get, path, params, api_version: api_version)
+    end
+
+    def post(path, body = {}, api_version: :v2)
+      request(:post, path, body, api_version: api_version)
+    end
+
+    def put(path, body = {}, api_version: :v2)
+      request(:put, path, body, api_version: api_version)
+    end
+
+    def delete(path, params = {}, api_version: :v2)
+      request(:delete, path, params, api_version: api_version)
+    end
+
+    private
+
+    def request(method, path, payload = {}, api_version: :v2)
+      response = connection.run_request(method, "#{base_url(api_version)}#{path}", nil, nil) do |req|
+        case method
+        when :get, :delete
+          req.params = payload if payload.any?
+        when :post, :put
+          req.body = JSON.generate(payload)
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def connection
+      @connection ||= Faraday.new do |f|
+        f.request :retry, max: 3, interval: 0.5, backoff_factor: 2,
+                          retry_statuses: [429, 500, 502, 503, 504],
+                          retry_block: ->(env:, options:, retry_count:, exception:, will_retry_in:) {
+                            handle_rate_limit(env) if env&.status == 429
+                          }
+        f.headers["X-Auth-Token"] = @config.access_token
+        f.headers["Content-Type"] = "application/json"
+        f.headers["Accept"] = "application/json"
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = @config.open_timeout
+      end
+    end
+
+    def base_url(api_version = :v2)
+      "#{BASE_URL}/#{@config.store_hash}/#{api_version}"
+    end
+
+    def handle_response(faraday_response)
+      response = Response.new(faraday_response)
+
+      case faraday_response.status
+      when 200..299
+        response
+      when 401
+        raise AuthenticationError.new("Invalid credentials", response: response)
+      when 404
+        raise NotFoundError.new("Resource not found", response: response)
+      when 422
+        raise UnprocessableEntityError.new(error_message(response), response: response)
+      when 429
+        raise RateLimitError.new("Rate limit exceeded", response: response)
+      when 500..599
+        raise ServerError.new("Server error", response: response)
+      else
+        raise ApiError.new(
+          error_message(response),
+          status: faraday_response.status,
+          body: response.body,
+          response: response
+        )
+      end
+    end
+
+    def error_message(response)
+      return "Unknown error" unless response.body.is_a?(Hash)
+
+      response.body[:title] || response.body[:message] || response.body.to_s
+    end
+
+    def handle_rate_limit(env)
+      reset_ms = env.response_headers&.dig("x-rate-limit-time-reset-ms")
+      sleep(reset_ms.to_f / 1000) if reset_ms
+    end
+  end
+end

data/lib/bigcommerce/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class UnprocessableEntityError < Error; end
+  class ServerError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil, response: nil)
+      @status = status
+      @body = body
+      super(message, response: response)
+    end
+
+    def to_s
+      "#{status}: #{message}"
+    end
+  end
+end

data/lib/bigcommerce/resource.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  class Resource
+    attr_reader :connection
+
+    def initialize(connection)
+      @connection = connection
+    end
+
+    private
+
+    def api_version
+      :v2
+    end
+
+    def get(path, params = {})
+      connection.get(path, params, api_version: api_version)
+    end
+
+    def post(path, body = {})
+      connection.post(path, body, api_version: api_version)
+    end
+
+    def put(path, body = {})
+      connection.put(path, body, api_version: api_version)
+    end
+
+    def delete(path, params = {})
+      connection.delete(path, params, api_version: api_version)
+    end
+  end
+end

data/lib/bigcommerce/resources/abandoned_cart_settings.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class AbandonedCartSettings < Resource
+      # GET /abandoned-carts/settings
+      # Get global abandoned cart settings.
+      # @return [Bigcommerce::Response]
+      def get_global
+        get("/abandoned-carts/settings")
+      end
+
+      # PUT /abandoned-carts/settings
+      # Update global abandoned cart settings.
+      # @param attributes [Hash] Settings attributes
+      # @option attributes [Boolean] :enable_notification Enable abandoned cart notifications
+      # @option attributes [Boolean] :email_customer_until_cart_is_recovered Email customer until cart is recovered
+      # @option attributes [Boolean] :marketing_emails_require_customer_consent Require customer consent for marketing emails
+      # @option attributes [Boolean] :email_merchant_when_cart_is_converted Email merchant when cart is converted
+      # @option attributes [Boolean] :email_merchant_when_cart_is_abandoned Email merchant when cart is abandoned
+      # @option attributes [String] :merchant_email_address Merchant email address
+      # @option attributes [String] :merchant_abandoned_cart_email_frequency_type Frequency type ("digest" or "individual")
+      # @option attributes [Integer] :merchant_abandoned_cart_digest_email_frequency Digest frequency (2-1000)
+      # @return [Bigcommerce::Response]
+      def update_global(**attributes)
+        put("/abandoned-carts/settings", attributes)
+      end
+
+      # GET /abandoned-carts/settings/channels/:channel_id
+      # Get channel-specific abandoned cart settings.
+      # @param channel_id [Integer] Channel ID
+      # @return [Bigcommerce::Response]
+      def get_channel(channel_id)
+        get("/abandoned-carts/settings/channels/#{channel_id}")
+      end
+
+      # PUT /abandoned-carts/settings/channels/:channel_id
+      # Update channel-specific abandoned cart settings.
+      # All fields are nullable — set to nil to inherit from global settings.
+      # @param channel_id [Integer] Channel ID
+      # @param attributes [Hash] Settings attributes (same as global, but all nullable)
+      # @return [Bigcommerce::Response]
+      def update_channel(channel_id, **attributes)
+        put("/abandoned-carts/settings/channels/#{channel_id}", attributes)
+      end
+
+      private
+
+      def api_version
+        :v3
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/abandoned_carts.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class AbandonedCarts < Resource
+      # GET /abandoned-carts/:token
+      # Returns the cart_id for a given abandoned cart token.
+      # The token is the UUID found in the query string of abandoned cart email links.
+      # @param token [String] Abandoned cart UUID token
+      # @return [Bigcommerce::Response]
+      def find(token)
+        get("/abandoned-carts/#{token}")
+      end
+
+      private
+
+      def api_version
+        :v3
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/inventory_adjustments.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class InventoryAdjustments < Resource
+      # PUT /inventory/adjustments/absolute
+      # Set inventory to an absolute quantity. Identifies items by location_id and
+      # one of: sku, variant_id, or product_id.
+      # @param items [Array<Hash>] Array of adjustment items
+      #   Each hash must include :location_id, :quantity, and one of :sku, :variant_id, or :product_id
+      # @param reason [String] Optional reason for the adjustment
+      # @return [Bigcommerce::Response]
+      def absolute(items:, reason: nil)
+        body = { items: items }
+        body[:reason] = reason if reason
+        put("/inventory/adjustments/absolute", body)
+      end
+
+      # POST /inventory/adjustments/relative
+      # Adjust inventory by a relative quantity (positive to add, negative to subtract).
+      # Identifies items by location_id and one of: sku, variant_id, or product_id.
+      # @param items [Array<Hash>] Array of adjustment items
+      #   Each hash must include :location_id, :quantity, and one of :sku, :variant_id, or :product_id
+      # @param reason [String] Optional reason for the adjustment
+      # @return [Bigcommerce::Response]
+      def relative(items:, reason: nil)
+        body = { items: items }
+        body[:reason] = reason if reason
+        post("/inventory/adjustments/relative", body)
+      end
+
+      private
+
+      def api_version
+        :v3
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/inventory_items.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class InventoryItems < Resource
+      # GET /inventory/items
+      # Get inventory at all locations.
+      # @param params [Hash] Query parameters
+      # @option params [String] :"sku:in" Comma-separated SKUs
+      # @option params [String] :"variant_id:in" Comma-separated variant IDs
+      # @option params [String] :"product_id:in" Comma-separated product IDs
+      # @option params [String] :"location_id:in" Comma-separated location IDs
+      # @option params [String] :"location_code:in" Comma-separated location codes
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/inventory/items", params)
+      end
+
+      # GET /inventory/locations/:location_id/items
+      # Get inventory at a specific location.
+      # @param location_id [Integer] Location ID
+      # @param params [Hash] Query parameters
+      # @option params [String] :"sku:in" Comma-separated SKUs
+      # @option params [String] :"variant_id:in" Comma-separated variant IDs
+      # @option params [String] :"product_id:in" Comma-separated product IDs
+      # @option params [Integer] :page Page number
+      # @option params [Integer] :limit Items per page
+      # @return [Bigcommerce::Response]
+      def list_for_location(location_id, **params)
+        get("/inventory/locations/#{location_id}/items", params)
+      end
+
+      # PUT /inventory/locations/:location_id/items
+      # Update inventory settings (safety_stock, is_in_stock, warning_level, bin_picking_number)
+      # for items at a specific location.
+      # @param location_id [Integer] Location ID
+      # @param settings [Array<Hash>] Array of setting objects
+      #   Each hash must include :identity (with :sku, :variant_id, or :product_id)
+      #   and at least one of: :safety_stock, :is_in_stock, :warning_level, :bin_picking_number
+      # @return [Bigcommerce::Response]
+      def update_settings(location_id, settings:)
+        put("/inventory/locations/#{location_id}/items", { settings: settings })
+      end
+
+      private
+
+      def api_version
+        :v3
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_coupons.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderCoupons < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/coupons
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/coupons", params)
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_fees.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderFees < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/fees
+      # @param id [Integer] Order ID
+      # @return [Bigcommerce::Response]
+      def list
+        get("/orders/#{@order_id}/fees")
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_messages.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderMessages < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/messages
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :min_id Minimum message ID
+      # @option params [Integer] :max_id Maximum message ID
+      # @option params [Integer] :customer_id Filter by customer ID
+      # @option params [String] :min_date_created Minimum date created
+      # @option params [String] :max_date_created Maximum date created
+      # @option params [Boolean] :is_flagged Filter by flagged status
+      # @option params [String] :status Filter by status (read, unread)
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/messages", params)
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_products.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderProducts < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/products
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/products", params)
+      end
+
+      # GET /orders/:order_id/products/:id
+      # @param id [Integer] Order product ID
+      # @return [Bigcommerce::Response]
+      def find(id)
+        get("/orders/#{@order_id}/products/#{id}")
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_shipments.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderShipments < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/shipments
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/shipments", params)
+      end
+
+      # GET /orders/:order_id/shipments/:id
+      # @param id [Integer] Shipment ID
+      # @return [Bigcommerce::Response]
+      def find(id)
+        get("/orders/#{@order_id}/shipments/#{id}")
+      end
+
+      # POST /orders/:order_id/shipments
+      # @param attributes [Hash] Shipment attributes
+      # @option attributes [Integer] :order_address_id Required - shipping address ID
+      # @option attributes [Array<Hash>] :items Required - [{order_product_id:, quantity:}]
+      # @option attributes [String] :tracking_number Tracking number
+      # @option attributes [String] :shipping_provider Shipping provider name
+      # @option attributes [String] :tracking_carrier Tracking carrier
+      # @option attributes [String] :tracking_link Tracking URL
+      # @option attributes [String] :merchant_shipping_cost Shipping cost (decimal string)
+      # @return [Bigcommerce::Response]
+      def create(**attributes)
+        post("/orders/#{@order_id}/shipments", attributes)
+      end
+
+      # PUT /orders/:order_id/shipments/:id
+      # @param id [Integer] Shipment ID
+      # @param attributes [Hash] Shipment attributes to update
+      # @return [Bigcommerce::Response]
+      def update(id, **attributes)
+        put("/orders/#{@order_id}/shipments/#{id}", attributes)
+      end
+
+      # DELETE /orders/:order_id/shipments/:id
+      # @param id [Integer] Shipment ID
+      # @return [Bigcommerce::Response]
+      def destroy(id)
+        delete("/orders/#{@order_id}/shipments/#{id}")
+      end
+
+      # DELETE /orders/:order_id/shipments
+      # Deletes all shipments for the order
+      # @return [Bigcommerce::Response]
+      def destroy_all
+        delete("/orders/#{@order_id}/shipments")
+      end
+
+      # GET /orders/:order_id/shipments/count
+      # @return [Bigcommerce::Response]
+      def count
+        get("/orders/#{@order_id}/shipments/count")
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_shipping_addresses.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderShippingAddresses < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/shipping_addresses
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/shipping_addresses", params)
+      end
+
+      # GET /orders/:order_id/shipping_addresses/:id
+      # @param id [Integer] Shipping address ID
+      # @return [Bigcommerce::Response]
+      def find(id)
+        get("/orders/#{@order_id}/shipping_addresses/#{id}")
+      end
+
+      # PUT /orders/:order_id/shipping_addresses/:id
+      # @param id [Integer] Shipping address ID
+      # @param attributes [Hash] Address attributes to update
+      # @return [Bigcommerce::Response]
+      def update(id, **attributes)
+        put("/orders/#{@order_id}/shipping_addresses/#{id}", attributes)
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_statuses.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderStatuses < Resource
+      # GET /order_statuses
+      # @return [Bigcommerce::Response]
+      def list
+        get("/order_statuses")
+      end
+
+      # GET /order_statuses/:id
+      # @param id [Integer] Status ID
+      # @return [Bigcommerce::Response]
+      def find(id)
+        get("/order_statuses/#{id}")
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/order_taxes.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class OrderTaxes < Resource
+      def initialize(connection, order_id)
+        super(connection)
+        @order_id = order_id
+      end
+
+      # GET /orders/:order_id/taxes
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @option params [String] :details Include tax details ('true' or 'false')
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders/#{@order_id}/taxes", params)
+      end
+    end
+  end
+end

data/lib/bigcommerce/resources/orders.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  module Resources
+    class Orders < Resource
+      # GET /orders
+      # @param params [Hash] Query parameters
+      # @option params [Integer] :min_id Minimum order ID
+      # @option params [Integer] :max_id Maximum order ID
+      # @option params [Float] :min_total Minimum order total
+      # @option params [Float] :max_total Maximum order total
+      # @option params [Integer] :customer_id Filter by customer ID
+      # @option params [String] :email Filter by customer email
+      # @option params [Integer] :status_id Filter by status ID
+      # @option params [String] :cart_id Filter by cart ID
+      # @option params [String] :payment_method Filter by payment method
+      # @option params [String] :min_date_created Minimum date created (RFC-2822 or ISO-8601)
+      # @option params [String] :max_date_created Maximum date created
+      # @option params [String] :min_date_modified Minimum date modified
+      # @option params [String] :max_date_modified Maximum date modified
+      # @option params [Integer] :page Page number (default: 1)
+      # @option params [Integer] :limit Results per page (default: 50)
+      # @option params [String] :sort Sort field (id, customer_id, date_created, date_modified, status_id, channel_id, external_id)
+      # @option params [Integer] :channel_id Filter by channel ID
+      # @option params [String] :external_order_id Filter by external order ID
+      # @option params [Array<String>] :include Side-load resources (consignments, consignments.line_items, fees)
+      # @return [Bigcommerce::Response]
+      def list(**params)
+        get("/orders", params)
+      end
+
+      # GET /orders/:id
+      # @param id [Integer] Order ID
+      # @param params [Hash] Query parameters
+      # @option params [Array<String>] :include Side-load resources
+      # @return [Bigcommerce::Response]
+      def find(id, **params)
+        get("/orders/#{id}", params)
+      end
+
+      # POST /orders
+      # @param attributes [Hash] Order attributes
+      # @return [Bigcommerce::Response]
+      def create(**attributes)
+        post("/orders", attributes)
+      end
+
+      # PUT /orders/:id
+      # @param id [Integer] Order ID
+      # @param attributes [Hash] Order attributes to update
+      # @return [Bigcommerce::Response]
+      def update(id, **attributes)
+        put("/orders/#{id}", attributes)
+      end
+
+      # DELETE /orders/:id
+      # Archives an order
+      # @param id [Integer] Order ID
+      # @return [Bigcommerce::Response]
+      def archive(id)
+        delete("/orders/#{id}")
+      end
+
+      # DELETE /orders
+      # Archives all orders (use with caution)
+      # @return [Bigcommerce::Response]
+      def archive_all
+        delete("/orders")
+      end
+
+      # GET /orders/count
+      # @param params [Hash] Same filter params as #list (except page/limit/sort/include)
+      # @return [Bigcommerce::Response]
+      def count(**params)
+        get("/orders/count", params)
+      end
+    end
+  end
+end

data/lib/bigcommerce/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(faraday_response)
+      @status = faraday_response.status
+      @headers = faraday_response.headers
+      @body = parse_body(faraday_response.body)
+    end
+
+    def success?
+      (200..299).cover?(status)
+    end
+
+    def rate_limit
+      headers["x-rate-limit-requests-left"]&.to_i
+    end
+
+    def rate_limit_reset
+      headers["x-rate-limit-time-reset-ms"]&.to_i
+    end
+
+    private
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError
+      raw
+    end
+  end
+end

data/lib/bigcommerce/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bigcommerce
+  VERSION = "0.2.0"
+end

data/lib/bigcommerce.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "bigcommerce/version"
+require_relative "bigcommerce/configuration"
+require_relative "bigcommerce/errors"
+require_relative "bigcommerce/response"
+require_relative "bigcommerce/connection"
+require_relative "bigcommerce/resource"
+require_relative "bigcommerce/client"
+require_relative "bigcommerce/resources/orders"
+require_relative "bigcommerce/resources/order_products"
+require_relative "bigcommerce/resources/order_shipments"
+require_relative "bigcommerce/resources/order_shipping_addresses"
+require_relative "bigcommerce/resources/order_coupons"
+require_relative "bigcommerce/resources/order_taxes"
+require_relative "bigcommerce/resources/order_messages"
+require_relative "bigcommerce/resources/order_fees"
+require_relative "bigcommerce/resources/order_statuses"
+require_relative "bigcommerce/resources/abandoned_carts"
+require_relative "bigcommerce/resources/abandoned_cart_settings"
+require_relative "bigcommerce/resources/inventory_items"
+require_relative "bigcommerce/resources/inventory_adjustments"
+
+module Bigcommerce
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def client(**options)
+      Client.new(**options)
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: bigcommerce-ruby
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Alvaro
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A lightweight Ruby wrapper for the BigCommerce V2 Orders API with support
+  for orders, shipments, products, and more.
+email:
+- aalvaaro@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/bigcommerce.rb
+- lib/bigcommerce/client.rb
+- lib/bigcommerce/configuration.rb
+- lib/bigcommerce/connection.rb
+- lib/bigcommerce/errors.rb
+- lib/bigcommerce/resource.rb
+- lib/bigcommerce/resources/abandoned_cart_settings.rb
+- lib/bigcommerce/resources/abandoned_carts.rb
+- lib/bigcommerce/resources/inventory_adjustments.rb
+- lib/bigcommerce/resources/inventory_items.rb
+- lib/bigcommerce/resources/order_coupons.rb
+- lib/bigcommerce/resources/order_fees.rb
+- lib/bigcommerce/resources/order_messages.rb
+- lib/bigcommerce/resources/order_products.rb
+- lib/bigcommerce/resources/order_shipments.rb
+- lib/bigcommerce/resources/order_shipping_addresses.rb
+- lib/bigcommerce/resources/order_statuses.rb
+- lib/bigcommerce/resources/order_taxes.rb
+- lib/bigcommerce/resources/orders.rb
+- lib/bigcommerce/response.rb
+- lib/bigcommerce/version.rb
+homepage: https://github.com/AAlvAAro/bigcommerce-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/AAlvAAro/bigcommerce-ruby
+  source_code_uri: https://github.com/AAlvAAro/bigcommerce-ruby
+  changelog_uri: https://github.com/AAlvAAro/bigcommerce-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the BigCommerce REST Management API
+test_files: []