API Endpoints

An event is when something interesting happens in your Sphere account.

When something interesting (e.g., a successful payment) occurs on your Sphere account, we create an event object that you can listen for through a webhook.

It is not uncommon for a single API request or key action on your platform to create multiple events. For example, when someone purchases a recurring product (e.g., a subscription) from a payment link or invoice, a subscription.created and payment.successful event will be created.

Let's look at an example event object. Don't worry about the length.

(It's mostly the data for the specific event (here, payment.successful) being passed back.)

The event object

{
  "id": "event_56c98d7fb4e64f9b867b4dc8997c0b13",
  "name": "payment.successful",
  "data": {
    "payment": {
      "id": "payment_d81efad665f649e2b0ea8b959feb6ee9",
      "type": "paymentLink",
      "status": "pending",
      "created": "2023-05-04T16:10:12.068Z",
      "invoice": null,
      "updated": "2023-05-04T16:10:12.068Z",
      "customer": {
        "id": "customer_2b2990e19b1a43c682d581e5e31aeada",
        "created": "2023-05-04T16:10:11.714Z",
        "updated": "2023-05-04T16:10:11.714Z",
        "delinquent": false,
        "personalInfo": {
          "id": "personalInfo_292e8febad504f6d891be5112e6a81ee",
          "email": "[email protected]",
          "address": {
            "geo": {
              "lat": null,
              "long": null
            },
            "city": "",
            "line1": "",
            "line2": "",
            "state": "",
            "country": "",
            "created": "2023-05-04T16:10:11.697Z",
            "updated": "2023-05-04T16:10:11.697Z",
            "postalCode": ""
          },
          "created": "2023-05-04T16:10:11.706Z",
          "updated": "2023-05-04T16:10:11.706Z",
          "lastName": "",
          "firstName": "adsg",
          "phoneNumber": ""
        },
        "solanaPubKey": "J3vUP1J72AjFKYUcFjo4oUTTv5ayrv7GhbBZQo7so1qw"
      },
      "transport": {
        "solana": {
          "id": "solanaTransport_8414e27703a646979b78f6c2d6ffd37d",
          "tx": "AqnsLfRylrNsoRhJb3d5x5cyDRXTWZ+IUnwzzhDLygq77CzgCH3szqlUulpi7W+J/cIY3EA0vQqDKb8O6vlFswMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAIAAwfZ99UgA2OCG0K8V2X8J6seRpJjjiDYu4HNDfzNeynCv/1WTOgIWp7DossY72B/JKiCKnGQ8CpzVCkVMlSGWpomAcj9bZyMLgZh+jk790qmQJ7CsTvks74Rd9hr/nPBwuN/9w4Aabb+dc+rWdp/HMrSUoPCom6JakfRiZGy++C4+QMGRm/lIRcy/+ytunLDm+e8jOW7xfcSayxDmzpAAAAAOI9idf3s5X8gY3HjwlqbxUiZ5cM/dze17aIY+/DCpAwGp9UXGSxcUSGMyUw9SvF/WNruCJuh/UTj29mKAAAAAMYPyOTUdVV14xvrQVMTp4tJDplivWZbdn7I1UBjx7bIAgQABQLAXBUABRAHAAABAQgJAgMKAwoDCwYMPHFhpQibvdDoIAAAAGhhc2hfNzVjMGJkOWFmN2MzNGIxMjgwNjg2N2I0NjBhmFMAAAAAAADghgEAAAAAAAED84lUVVPga8IpchNrNiIwclxV/+xpGiuS7d+jn4m8cQELBRIUBRMH",
          "hash": "hash_75c0bd9af7c34b12806867b460a",
          "swapTx": {},
          "created": "2023-05-04T16:10:11.709Z",
          "updated": "2023-05-04T16:10:12.059Z",
          "solanaEvent": null
        }
      },
      "paymentLink": {
        "id": "paymentLink_1aad1e1f6d7942d5b861ed32a46156e0",
        "url": "http://localhost:3000/pay/paymentLink_1aad1e1f6d7942d5b861ed32a46156e0",
        "meta": {},
        "name": "",
        "created": "2023-05-04T16:09:56.990Z",
        "failUrl": "",
        "updated": "2023-05-04T16:09:56.990Z",
        "features": {
          "requiresName": true,
          "requiresEmail": true,
          "requiresShippingDetails": false
        },
        "lineItems": [
          {
            "id": "lineItem_b6416dd7d91c429f80ad491260dc93e4",
            "name": "lineItem_b6416dd7d91c429f80ad491260dc93e4",
            "price": {
              "id": "price_d54154545feb4aa0b3da5013c35b81c3",
              "meta": {},
              "name": null,
              "type": "oneTime",
              "tiers": [],
              "active": true,
              "created": "2023-05-04T16:09:44.407Z",
              "network": null,
              "product": {
                "id": "product_38f38fbef96848888659cac45acdc0eb",
                "meta": {},
                "name": "asdg",
                "tags": [],
                "images": [],
                "prices": [],
                "created": "2023-05-04T16:09:44.455Z",
                "updated": "2023-05-04T16:09:44.455Z",
                "description": "asdgasdg"
              },
              "updated": "2023-05-04T16:09:44.455Z",
              "currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
              "tierType": null,
              "lookupKey": null,
              "recurring": {
                "interval": null,
                "usageType": null,
                "defaultLength": null,
                "intervalCount": null,
                "usageAggregation": null
              },
              "unitAmount": "21400",
              "description": null,
              "taxBehavior": "exclusive",
              "billingScheme": "perUnit",
              "currencyOptions": [],
              "customUnitAmount": {
                "max": null,
                "min": null,
                "preset": null
              },
              "unitAmountDecimal": 0.0214
            },
            "created": "2023-05-04T16:09:56.990Z",
            "updated": "2023-05-04T16:09:56.990Z",
            "quantity": 1,
            "description": "",
            "quantityMutable": false
          }
        ],
        "successUrl": "",
        "application": {
          "id": "application_bb6754ed346341b19320ad69acdba21e",
          "name": "default",
          "user": {},
          "image": null,
          "created": "2023-05-04T16:08:57.285Z",
          "updated": "2023-05-04T16:08:57.285Z",
          "nickname": null,
          "isDefault": true,
          "proxySolanaPubKey": null
        },
        "description": ""
      },
      "personalInfo": {
        "id": "personalInfo_292e8febad504f6d891be5112e6a81ee",
        "email": "[email protected]",
        "address": {
          "geo": {
            "lat": null,
            "long": null
          },
          "city": "",
          "line1": "",
          "line2": "",
          "state": "",
          "country": "",
          "created": "2023-05-04T16:10:11.697Z",
          "updated": "2023-05-04T16:10:11.697Z",
          "postalCode": ""
        },
        "created": "2023-05-04T16:10:11.706Z",
        "updated": "2023-05-04T16:10:11.706Z",
        "lastName": "",
        "firstName": "adsg",
        "phoneNumber": ""
      },
      "transactions": []
    }
  },
  "mock": true,
  "updated": "2021-01-01T00:00:00.000Z",
  "created": "2021-01-01T00:00:00.000Z"
}

As you can see, the event records all of the relevant information about the resource it is attached to.

However, if we drill down into the object, there are just a couple of key fields:

{
  "id": "event_56c98d7fb4e64f9b867b4dc8997c0b13",
  "name": "payment.successful",
  "data": {
    "..."
  },
  "mock": true,
  "created": "2021-01-01T00:00:00.000Z",
  "updated": "2021-01-01T00:00:00.000Z"
}

id: a string that Sphere auto-generates for you upon creation.

name: the particular event that occurred.

data: the relevant information about the resource the event is associated with.

mock: a boolean that indicates whether the event was a test generated by the mock API.

updated and created are string timestamps following the JavaScript date time string format that describe when the product was last updated and when it was created.

Available Events

enum EVENT_NAMES {
  
  // Address
  CREATE_ADDRESS = "address.create",
  
  // Alert
  CREATE_ALERT = "alert.create",
  UPDATE_ALERT = "alert.update",
  
  // Tax Rate
  CREATE_TAX_RATE = "taxRate.create",
  DELETE_TAX_RATE = "taxRate.delete",
  UPDATE_TAX_RATE = "taxRate.update",
  
  // Escrow
  CREATE_ESCROW = "escrow.create",
  UPDATE_ESCROW = "escrow.update",
  DISBURSE_ESCROW = "escrow.disburse",
  
  // ApiKey
  CREATE_API_KEY = "apiKey.create",
  UPDATE_API_KEY = "apiKey.update",
  DELETE_API_KEY = "apiKey.delete",
  
  // Customer
  CREATE_CUSTOMER = "customer.create",
  UPDATE_CUSTOMER = "customer.update",
  
  // EMAIL
  CREATE_EMAIL = "email.create",
  
  // FILE
  CREATE_FILE = "file.create",
  
  // Impression
  CREATE_IMPRESSION = "impression.create",
  UPDATE_IMPRESSION = "impression.update",
  
  // Metric
  UPDATE_METRIC = "metric.update",
  
  // Payment
  PENDING_PAYMENT = "payment.pending",
  CANCELLED_PAYMENT = "payment.cancelled",
  SUCCESSFUL_PAYMENT = "payment.successful",
  INCOMPLETE_PAYMENT = "payment.incomplete",
  UPDATE_PAYMENT = "payment.update",
  FAILED_PAYMENT = "payment.failed",
  
  // PaymentLink
  CREATE_PAYMENT_LINK = "paymentLink.create",
  DELETE_PAYMENT_LINK = "paymentLink.delete",
  UPDATE_PAYMENT_LINK = "paymentLink.update",
  
  // Price
  CREATE_PRICE = "price.create",
  DELETE_PRICE = "price.delete",
  UPDATE_PRICE = "price.update",
  
  // Product
  CREATE_PRODUCT = "product.create",
  DELETE_PRODUCT = "product.delete",
  UPDATE_PRODUCT = "product.update",
  
  // Refund
  PENDING_REFUND = "refund.pending",
  SUCCESSFUL_REFUND = "refund.successful",
  INCOMPLETE_REFUND = "refund.incomplete",
  FAILED_REFUND = "refund.failed",
  UPDATE_REFUND = "refund.update",
  
  // Transaction
  CREATE_TRANSACTION = "transaction.create",
  UPDATE_TRANSACTION = "transaction.update",
  
  // Subscription
  BILL_SUBSCRIPTION = "subscription.bill",
  APPROVE_SUBSCRIPTION = "subscription.approve",
  LOW_BALANCE_ESCROWED_SUBSCRIPTION = "subscription.escrowed.low_balance",
  LOW_BALANCE_DELEGATED_SUBSCRIPTION = "subscription.delegated.low_balance",
  INSUFFICIENT_DELEGATED_BALANCE_SUBSCRIPTION = "subscription.delegated.insufficient_balance",
  INSUFFICIENT_DELEGATED_APPROVED_SUBSCRIPTION = "subscription.delegated.insufficient_approved",
  INSUFFICIENT_ESCROWED_BALANCE = "subscription.escrowed.insufficient_balance",
  REDELEGATED_SUBSCRIPTION = "subscription.delegated.redelegated",
  
  CREATE_SUBSCRIPTION = "subscription.create",
  PAST_DUE_SUBSCRIPTION = "subscription.pastDue",
  DELETE_SUBSCRIPTION = "subscription.delete",
  UPDATE_SUBSCRIPTION = "subscription.update",
  
  // Usage Record
  CREATE_USAGE_RECORD = "usageRecord.create",
  
  // Webhook
  CREATE_WEBHOOK = "webhook.create",
  DELETE_WEBHOOK = "webhook.delete",
  UPDATE_WEBHOOK = "webhook.update",
  
  // Bank Account
  CREATE_BANK_ACCOUNT = "bank_account.create",
  DELETE_BANK_ACCOUNT = "bank_account.delete",
  UPDATE_BANK_ACCOUNT = "bank_account.update",
  
  // Payout
  CREATE_PAYOUT = "payout.create",
  DELETE_PAYOUT = "payout.delete",
  UPDATE_PAYOUT = "payout.update",
  SUCCESSFUL_PAYOUT = "payout.success",
  FAILED_PAYOUT = "payout.failed"
}