> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/developer-tools/next-js/sdk-reference/usesubscription.md).

# useSubscription

{% hint style="info" %}
**This page's documentation only applies to Chord's** [**Next.js starter**](https://github.com/chordcommerce/nextjs-starter-autonomy) **prior to the release of the** [React](/chord-oms/developer-tools/react.md)**. The Next.js starter now uses the React SDK and does not use the methods documented on this page. Check out the** [**React SDK Reference**](https://docs-beta.chord.co/chord-ui/module-react-autonomy) **for complete documentation, and the** [React SDK Migration Guide](/chord-oms/developer-tools/next-js/guides/react-sdk-migration-guide.md)**for details on how to upgrade.**
{% endhint %}

The `useSubscription` hook returns the current loaded subscription and functions for managing the subscription.

## Example

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {
  const { subscription } = useSubscription()

  return (
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>
  )
}
```

```javascript
import { useSubscription } from '~/hooks/actions'

// inside a function component
const { subscripion, loadSubscription } = useSubscription()
```

## Returns

The `useSubscription` hook returns an object with these properties:

| Property             | Description                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `subscription`       | An object representing a subscription. You will need to explicitly call `loadSubscription` before this object will be populated. |
| `loadSubscription`   | A function that loads the subscription.                                                                                          |
| `skipSubscription`   | A function that skips the next subscription delivery.                                                                            |
| `cancelSubscription` | A function that cancels the subscription.                                                                                        |
| `pauseSubscription`  | A function that pauses the subscription.                                                                                         |
| `resumeSubscription` | A function that resumes the subscription.                                                                                        |
| `updateSubscription` | A function that updates the subscription.                                                                                        |

## Functions

### loadSubscription

The `loadSubscription` function loads information about the subscription from the Chord API.

**Arguments:**

`loadSubscription(subscriptionId)`

| Argument         | Type   | Description                           |
| ---------------- | ------ | ------------------------------------- |
| `subscriptionId` | Number | The `id` of the subscription to load. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {
  const { subscription, loadSubscription } = useSubscription()

  useEffect(() => {
    loadSubscription(subscriptionId)
  }, [])

  return (
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>
  )
}
```

### skipSubscription

The `skipSubscription` function calls the Chord API to skip the next subscription delivery.

**Arguments:**

None.

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {
  const { subscription, skipSubscription } = useSubscription()

  useEffect(() => {
    skipSubscription()
  }, [])

  return (
    <p>Your subscription will be renewed on {subscription.actionableDate}</p>
  )
}
```

### cancelSubscription

The `cancelSubscription` function calls the Chord API to cancel a subscription.

**Arguments:**

None.

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default subscriptionId => {
  const { subscription, cancelSubscription } = useSubscription()

  useEffect(() => {
    cancelSubscription()
  }, [])

  return <p>Your subscription was canceled</p>
}
```

### pauseSubscription

The`pauseSubscription` function calls the Chord API to pause a subscription.

Paused subscriptions will not be processed until manually`resumed`or the`actionableDate`is reached.

**Arguments:**

`pauseSubscription(options)`

| Argument                   | Type   | Description                                                                                                                                                                                 |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?.actionableDate?` | String | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be paused indefinitely. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {
  const { pauseSubscription } = useSubscription(subscription.id)
  const onSubmit = async data => {
    try {
      let response = await pauseSubscription({
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error)
    }
  }
}
```

### resumeSubscription

The`resumeSubscription`function calls the Chord API to resume a subscription.

Paused subscriptions will not be processed until manually`resumed`or the`actionableDate`is reached.

**Arguments:**

`resumeSubscription(options)`

| Argument                   | Type   | Description                                                                                                                                                                                  |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?.actionableDate?` | String | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be resumed the next day. |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {
  const { resumeSubscription } = useSubscription(subscription.id)
  const onSubmit = async data => {
    try {
      let response = await resumeSubscription({
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error)
    }
  }
}
```

### updateSubscription

The`updateSubscription` function calls the Chord API to update a subscription.

**Arguments:**

`updateSubscription(options)`

| Argument                         | Type                                   | Description                                                                                                                                                                                  |
| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options.actionableDate?`        | String                                 | (Optional): A date string representing when the subscription should resume. The minimum date is the next day. If `actionableDate` is omitted, the subscription will be resumed the next day. |
| `options.billAddressAttributes?` | Object                                 | (Optional) An object representing the billing address. All fields need to be sent even if only a single field is updated.                                                                    |
| `options.endDate?`               | String \| Null                         | (Optional) A string representing the end date of the subscription. If `null`, the subscription will renew indefinitely.                                                                      |
| `options.shipAddressAttributes?` | Object                                 | (Optional) An object representing the shipping address. All fields need to be sent even if only a single field is updated.                                                                   |
| `options.intervalLength?`        | Number                                 | (Optional): The number of units. *Example:* if the subscription should be delivered every three months, this would be `3`.                                                                   |
| `options.intervalUnit?`          | `"day" \| "week" \| "month" \| "year"` | (Optional): The interval unit. *Example:* if the subscription should be delivered every three months, this would be `month`.                                                                 |

**Returns:**

`Promise<Subscription>`: A Promise that resolves with the subscription.

**Example:**

```javascript
import { useSubscription } from '~/hooks/actions'

export default () => {
  const { updateSubscription } = useSubscription(subscription.id)
  const onSubmit = async data => {
    try {
      let response = await updateSubscription({
        'shipAddressAttributes': data.addressAttributes,
        'billAddressAttributes': data.addressAttributes,
        'intervalUnits': 'month',
        'intervalLength': 2,
        'endDate': '2021/12/31',
        'actionableDate': '2030-08-18'
      })
      console.log(response)
    } catch (error) {
      console.error(error)
    }
  }
}

/*
  Default Form Values:

  const address = subscription['shipAddress']
  const addressAttributes = {
    name: address.name,
    address1: address.address1,
    address2: address.address2,
    city: address.city,
    state_name: address.state.abbr,
    country_iso: address.country.iso,
    zipcode: address.zipcode
  }
*/
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/chord-oms/developer-tools/next-js/sdk-reference/usesubscription.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.